@loradb/lora-node 0.35.1 → 0.36.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/README.md +5 -0
  2. package/dist/types.d.ts +2 -1
  3. package/dist/types.d.ts.map +1 -1
  4. package/dist/types.js +1 -0
  5. package/dist/types.js.map +1 -1
  6. package/docs/README.md +86 -0
  7. package/docs/concepts/graph-model.md +270 -0
  8. package/docs/concepts/nodes.md +285 -0
  9. package/docs/concepts/properties.md +348 -0
  10. package/docs/concepts/relationships.md +325 -0
  11. package/docs/concepts/result-formats.md +183 -0
  12. package/docs/concepts/schema-free.md +183 -0
  13. package/docs/cookbook.md +1081 -0
  14. package/docs/data-types/lists-and-maps.md +406 -0
  15. package/docs/data-types/overview.md +210 -0
  16. package/docs/data-types/scalars.md +376 -0
  17. package/docs/data-types/spatial.md +291 -0
  18. package/docs/data-types/temporal.md +349 -0
  19. package/docs/data-types/vectors.md +563 -0
  20. package/docs/errors.md +183 -0
  21. package/docs/functions/aggregation.md +372 -0
  22. package/docs/functions/list.md +522 -0
  23. package/docs/functions/map.md +207 -0
  24. package/docs/functions/math.md +421 -0
  25. package/docs/functions/number.md +197 -0
  26. package/docs/functions/overview.md +545 -0
  27. package/docs/functions/spatial.md +384 -0
  28. package/docs/functions/string.md +502 -0
  29. package/docs/functions/temporal.md +590 -0
  30. package/docs/functions/utility.md +137 -0
  31. package/docs/functions/vectors.md +772 -0
  32. package/docs/getting-started/installation.md +204 -0
  33. package/docs/getting-started/node.md +582 -0
  34. package/docs/getting-started/tutorial.md +334 -0
  35. package/docs/index.md +203 -0
  36. package/docs/limitations.md +291 -0
  37. package/docs/performance.md +219 -0
  38. package/docs/queries/aggregation.md +520 -0
  39. package/docs/queries/cheat-sheet.md +302 -0
  40. package/docs/queries/constraints.md +239 -0
  41. package/docs/queries/create.md +331 -0
  42. package/docs/queries/examples.md +453 -0
  43. package/docs/queries/index.md +169 -0
  44. package/docs/queries/indexes.md +538 -0
  45. package/docs/queries/match.md +429 -0
  46. package/docs/queries/ordering.md +359 -0
  47. package/docs/queries/parameters.md +328 -0
  48. package/docs/queries/paths.md +462 -0
  49. package/docs/queries/return-with.md +500 -0
  50. package/docs/queries/set-delete.md +369 -0
  51. package/docs/queries/unwind-merge.md +358 -0
  52. package/docs/queries/where.md +416 -0
  53. package/docs/snapshot.md +545 -0
  54. package/docs/troubleshooting.md +1158 -0
  55. package/docs/wal.md +570 -0
  56. package/docs/why.md +273 -0
  57. package/package.json +13 -14
@@ -0,0 +1,545 @@
1
+ ---
2
+ title: "Built-in Functions in LoraDB"
3
+ description: "How LoraDB functions work — namespaces, compatibility aliases, casts, null and error behavior, aggregate behavior, and links to each per-category reference."
4
+ online: "https://loradb.com/docs/functions/overview"
5
+ package: "@loradb/lora-node@0.36.1"
6
+ ---
7
+
8
+ # Built-in Functions in LoraDB
9
+
10
+ Functions are expressions. You can use them anywhere an expression is
11
+ accepted: in `RETURN`, `WITH`, `WHERE`, `ORDER BY`, `SET`, map
12
+ projections, list comprehensions, and nested inside other function
13
+ calls.
14
+
15
+ ```cypher
16
+ MATCH (d:Doc)
17
+ WITH d,
18
+ vector.similarity(d.embedding, $query) AS score,
19
+ temporal.truncate('month', d.published_at) AS month
20
+ WHERE score >= 0.75
21
+ RETURN d.title, month, score
22
+ ORDER BY score DESC
23
+ LIMIT 10
24
+ ```
25
+
26
+ Function names are **case-insensitive**. Canonical LoraDB functions are
27
+ mostly namespaced, such as `string.lower`, `math.sqrt`, `list.range`,
28
+ `temporal.now`, `geo.distance`, `vector.similarity`, `type.of`, and
29
+ `cast.try`. A small set of historical and convenience aliases remains
30
+ for common Cypher-style helpers and zero-argument value helpers, such as
31
+ `toInteger`, `toString`, `size`, `head`, `length`, `coalesce`, and
32
+ `now`.
33
+
34
+ The analyzer resolves every function call before execution. That means
35
+ unknown names, wrong argument counts, unknown type literals, and invalid
36
+ enum literals such as vector metric names are rejected before rows are
37
+ scanned. The executor then evaluates only validated calls.
38
+
39
+ Most functions **propagate `null`** — any `null` argument makes the
40
+ result `null`. The exceptions are aggregates, `coalesce`, current-time
41
+ helpers, and constants/random helpers.
42
+
43
+ ## Function expression basics
44
+
45
+ Functions do not introduce a new query clause. They are part of the
46
+ expression language, so they evaluate once for each row flowing through
47
+ the clause that contains them.
48
+
49
+ ```cypher
50
+ MATCH (u:User)
51
+ WITH u, string.lower(u.email) AS email
52
+ WHERE email ENDS WITH '@loradb.com'
53
+ RETURN u.name, email
54
+ ORDER BY email
55
+ ```
56
+
57
+ In that query:
58
+
59
+ - `string.lower(u.email)` runs for each matched `User` row.
60
+ - `WITH` gives the result a name so later clauses can reuse it.
61
+ - `WHERE`, `RETURN`, and `ORDER BY` all see the shaped row from `WITH`.
62
+
63
+ Functions are side-effect free. They cannot create nodes, update
64
+ properties, query indexes by themselves, or change the graph. Graph
65
+ writes still happen through clauses such as `CREATE`, `MERGE`, `SET`,
66
+ and `DELETE`; functions only compute values for those clauses to use.
67
+
68
+ ## Reading signatures and examples
69
+
70
+ Function pages use compact signatures:
71
+
72
+ | Notation | Meaning |
73
+ |---|---|
74
+ | `fn(x)` | one required argument |
75
+ | `fn(x[, y])` | `y` is optional |
76
+ | `fn(a, b, ...)` | accepts a variable number of arguments |
77
+ | `LIST<T>` | a list whose elements are usually the same type |
78
+ | `null → null` | a null input returns null instead of an error |
79
+
80
+ Examples are written as complete Cypher fragments whenever possible.
81
+ Comments show representative results, not a promise about exact display
82
+ format in every host binding.
83
+
84
+ ```cypher
85
+ RETURN string.slice('loradb', 0, 4); // 'lora'
86
+ RETURN '2024-01-15'::DATE; // DATE value
87
+ RETURN TRY_CAST('not a date' AS DATE) // null
88
+ ```
89
+
90
+ ## How functions are organised
91
+
92
+ LoraDB keeps value construction and value operations separate:
93
+
94
+ | Use case | Preferred syntax | Why |
95
+ |---|---|---|
96
+ | Build a typed value in query text | `'2024-01-15'::DATE`, `{x: 1, y: 2}::POINT`, `[1,2,3]::VECTOR<INTEGER>(3)` | Casts make the target type explicit. |
97
+ | Convert with CAST syntax | `CAST(value AS TYPE)` | First-class Cypher grammar for strict conversion. |
98
+ | Convert without throwing | `TRY_CAST(value AS TYPE)` | Nullable cast; returns `null` when conversion fails. |
99
+ | Ask about a value's type | `type.of(value)` | Returns tags such as `"DATE"` or `"VECTOR<FLOAT32>(384)"`. |
100
+ | Work with temporal values | `temporal.now()`, `temporal.truncate('month', d)` | Current-time helpers and temporal operations. |
101
+ | Work with points | `geo.distance(a, b)`, `geo.within_bbox(p, ll, ur)` | Spatial operations over existing `POINT` values. |
102
+ | Work with vectors | `vector.similarity(a, b)`, `vector.distance(a, b, EUCLIDEAN)` | Vector math over existing `VECTOR` values. |
103
+
104
+ The important distinction: `temporal.*`, `geo.*`, and `vector.*` are
105
+ operation namespaces. They are not the default way to construct
106
+ `DATE`, `POINT`, or `VECTOR` values in query text.
107
+
108
+ ```cypher
109
+ RETURN '2024-01-15'::DATE,
110
+ CAST('2024-01-15' AS DATE),
111
+ TRY_CAST($maybe_date AS DATE)
112
+ ```
113
+
114
+ Use host-language helpers separately when binding parameters from
115
+ Node, Python, Go, Ruby, WASM, or Rust. For example, a Node query may
116
+ bind `{ at: datetime("2026-05-01T09:00:00Z") }`, but the equivalent
117
+ query-text literal is `'2026-05-01T09:00:00Z'::DATETIME`.
118
+
119
+ ### Choosing a construction form
120
+
121
+ Use the form that best matches where the value comes from:
122
+
123
+ | Source value | Recommended query syntax | Notes |
124
+ |---|---|---|
125
+ | Literal ISO date/time text | `'2026-05-01'::DATE` | Most readable for handwritten queries. |
126
+ | Literal map point | `{longitude: 4.89, latitude: 52.37}::POINT` | Lets the `POINT` cast validate CRS/SRID rules. |
127
+ | Literal numeric vector | `[0.1, 0.2, 0.3]::VECTOR<FLOAT32>(3)` | Dimension and coordinate type are visible at the use site. |
128
+ | Parameter that may be invalid | `TRY_CAST($value AS DATE)` | Returns `null`, so pair it with `IS NOT NULL` or `coalesce`. |
129
+ | Generated query text | `CAST($value AS DATE)` | Strict conversion using the Cypher grammar. |
130
+
131
+ Strict casts are useful when bad input should stop the query. `TRY_CAST`
132
+ is better for ingestion and optional filters, where a failed conversion
133
+ should become `null` and be handled by normal Cypher predicates.
134
+
135
+ The older constructor-shaped temporal, spatial, and vector forms are not
136
+ the preferred public query syntax. Use casts in query text, and use
137
+ client-library binding helpers only when creating parameters in a host
138
+ language.
139
+
140
+ ## Calling functions
141
+
142
+ A function call has three parts: the name, the arguments, and sometimes
143
+ a literal type or option argument.
144
+
145
+ ```cypher
146
+ RETURN string.lower('LORA') AS name,
147
+ math.round(3.14159, 2) AS rounded,
148
+ vector.distance($a, $b, EUCLIDEAN) AS distance,
149
+ TRY_CAST($raw AS DATE) AS maybe_date
150
+ ```
151
+
152
+ Namespaced functions are ordinary expression functions. They do not
153
+ require `CALL`, do not stream rows by themselves, and can be nested
154
+ inside other expressions:
155
+
156
+ ```cypher
157
+ MATCH (d:Doc)
158
+ WHERE type.of(d.published_at) = 'DATE'
159
+ RETURN string.upper(coalesce(d.title, 'untitled')) AS title,
160
+ temporal.truncate('year', d.published_at) AS year
161
+ ```
162
+
163
+ Some arguments are not values from the graph; they are compile-time
164
+ symbols:
165
+
166
+ | Symbol kind | Used by | Example |
167
+ |---|---|---|
168
+ | Type literal | casts and type checks | `TRY_CAST($x AS INTEGER)`, `type.is($x, DATE)` |
169
+ | Vector metric | vector distance and norm | `vector.distance(a, b, EUCLIDEAN)`, `vector.norm(v, MANHATTAN)` |
170
+
171
+ Vector metrics can also be supplied as strings when that is more
172
+ convenient for generated queries. If the target type itself must be
173
+ dynamic, use the lower-level `cast.to` / `cast.try` helpers with a type
174
+ string:
175
+
176
+ ```cypher
177
+ RETURN cast.try($raw, $type_name) AS maybe_date,
178
+ vector.distance($a, $b, 'euclidean') AS distance
179
+ ```
180
+
181
+ ## Namespaces and aliases
182
+
183
+ Canonical names are deliberately explicit:
184
+
185
+ | Namespace | Contains | Examples |
186
+ |---|---|---|
187
+ | `string.*` | string case, search, tokenizing, slicing, regex, encoding | `string.lower(x)`, `string.words(x)`, `string.count(x, needle)` |
188
+ | `math.*` | arithmetic helpers, trig, constants, random | `math.abs(x)`, `math.hypot(a, b)`, `math.random()` |
189
+ | `number.*` / `bits.*` | numeric formatting, base conversion, numeric predicates, bit operations | `number.format(n, 2)`, `number.to_base(n, 16)`, `bits.and(a, b)` |
190
+ | `list.*` | list construction, indexing, and transforms | `list.range(1, 10)`, `list.at(xs, -1)`, `list.take_last(xs, 3)` |
191
+ | `map.*` | map lookup, patching, projection, deep merge, nested paths, entries, flattening | `map.get(m, 'k')`, `map.get_path(m, 'a.b')`, `map.deep_merge(a, b)` |
192
+ | `temporal.*` | current time, truncation, differences, fields | `temporal.now()`, `temporal.today()`, `temporal.between(a, b)` |
193
+ | `geo.*` | spatial predicates and distances | `geo.distance(a, b)`, `geo.within_bbox(p, ll, ur)` |
194
+ | `vector.*` | similarity, distance, norms, vector shape | `vector.similarity(a, b)`, `vector.dimension(v)` |
195
+ | `text.*` | string distance, similarity, and phonetic helpers | `text.distance(a, b, 'levenshtein')`, `text.phonetic(s, 'soundex')` |
196
+ | `bytes.*` / `crypto.*` | byte conversion, compression, and hashes | `bytes.base64_encode(x)`, `crypto.blake3(x)` |
197
+ | `uuid.*` / `json.*` | UUID generation/validation and JSON encoding/path access | `uuid.new()`, `json.path(x, '$.a[0]')` |
198
+ | `path.*` | path decomposition and path length | `path.nodes(p)`, `path.edges(p)`, `path.length(p)` |
199
+ | `node.*` / `edge.*` | node and relationship introspection | `node.labels(n)`, `edge.type(r)` |
200
+ | `type.*` | runtime type inspection and checks | `type.of(x)`, `type.is(x, DATE)` |
201
+ | `cast.*` | explicit conversion helpers | `cast.to(x, DATE)`, `cast.try(x, INTEGER)` |
202
+ | `value.*` | polymorphic value helpers | `value.size(x)`, `value.keys(x)`, `value.coalesce(a, b)` |
203
+
204
+ Compatibility aliases exist for common Cypher spellings:
205
+
206
+ | Alias | Canonical behavior |
207
+ |---|---|
208
+ | `toString(x)` | `x::STRING` / `CAST(x AS STRING)` |
209
+ | `toInteger(x)` | `x::INTEGER` / `CAST(x AS INTEGER)` |
210
+ | `toIntegerOrNull(x)` | `TRY_CAST(x AS INTEGER)` |
211
+ | `size(x)` | `value.size(x)` |
212
+ | `head(xs)` / `last(xs)` | list first / last helpers |
213
+ | `id(x)`, `labels(n)`, `type(r)` | entity introspection helpers |
214
+ | `now()` | `temporal.now()` |
215
+ | `timestamp()` | `temporal.timestamp()` |
216
+ | `timezone()` | `temporal.timezone()` |
217
+ | `new()` | `uuid.new()` |
218
+ | `random()` | `math.random()` |
219
+
220
+ Prefer canonical names in new documentation when the namespace clarifies
221
+ intent. Use aliases where they are the familiar Cypher form and already
222
+ documented on the category page.
223
+
224
+ ## Category guide
225
+
226
+ The function library is intentionally small. Each category covers one
227
+ kind of value work:
228
+
229
+ | Category | Use it for | Good first function |
230
+ |---|---|---|
231
+ | Aggregation | Collapsing many rows into grouped summaries | `count(*)` |
232
+ | String | Cleaning, slicing, parsing, and comparing text | `string.trim`, `string.lower` |
233
+ | Math | Numeric formulas and random/constants | `math.round`, `math.sqrt` |
234
+ | Number | Formatting, radix conversion, integer predicates, and bit helpers | `number.format`, `number.to_base` |
235
+ | List | Selecting, reshaping, and reducing list values | `value.size`, `list.range` |
236
+ | Temporal | Current time, calendar math, truncation, date differences | `temporal.now()` |
237
+ | Spatial | Point distance, bounding boxes, CRS-aware component access | `geo.distance` |
238
+ | Vector | Embedding similarity, distance metrics, vector introspection | `vector.similarity` |
239
+ | Entity/value | Inspecting graph values, maps, and runtime types | `value.properties`, `type.of` |
240
+
241
+ If a task needs graph traversal, start with a pattern in `MATCH`. If it
242
+ needs row grouping, start with aggregation. If it needs to reshape a
243
+ single value already in the row, reach for a scalar function.
244
+
245
+ ```cypher
246
+ // Traversal first, then scalar functions, then aggregation.
247
+ MATCH (u:User)-[:POSTED]->(p:Post)
248
+ WITH u, temporal.truncate('month', p.created_at) AS month
249
+ RETURN u.id, month, count(*) AS posts
250
+ ORDER BY month
251
+ ```
252
+
253
+ ## Errors and nulls
254
+
255
+ For a single expression, LoraDB distinguishes validation failures,
256
+ runtime conversion failures, ordinary null propagation, and aggregate
257
+ semantics.
258
+
259
+ ### Validation errors
260
+
261
+ These are rejected while the query is analyzed:
262
+
263
+ - unknown function names
264
+ - wrong argument counts
265
+ - invalid type names in `CAST`, `TRY_CAST`, `cast.to`, or `cast.try`
266
+ - invalid vector metrics in `vector.distance` or `vector.norm`
267
+
268
+ For example, `vector.distance(a, b)` is invalid because distance needs a
269
+ metric, and `vector.distance(a, b, BOGUS)` is invalid because `BOGUS` is
270
+ not a supported metric.
271
+
272
+ ### Conversion errors
273
+
274
+ | Situation | Result |
275
+ |---|---|
276
+ | Unknown function or wrong argument count | analysis error before execution |
277
+ | Invalid strict conversion, such as `'bad'::DATE` | runtime error |
278
+ | Nullable conversion, such as `TRY_CAST('bad' AS DATE)` | `null` |
279
+
280
+ Strict casts are for inputs that must be valid. Nullable casts are for
281
+ ingestion, optional filters, and user-supplied values where invalid data
282
+ should simply disappear from the result:
283
+
284
+ ```cypher
285
+ UNWIND $rows AS row
286
+ WITH row, TRY_CAST(row.signup_date AS DATE) AS signup_date
287
+ WHERE signup_date IS NOT NULL
288
+ CREATE (:Signup {email: row.email, signup_date: signup_date})
289
+ ```
290
+
291
+ ### Null propagation
292
+
293
+ Most non-aggregate functions follow normal null propagation:
294
+
295
+ ```cypher
296
+ RETURN geo.distance(null, {x: 1, y: 2}::POINT), // null
297
+ vector.similarity(null, [1, 2, 3]::VECTOR<INTEGER>(3)), // null
298
+ temporal.truncate('month', null), // null
299
+ coalesce(null, 'fallback') // 'fallback'
300
+ ```
301
+
302
+ That behavior is intentional: missing input usually means missing output,
303
+ and the query can decide how to handle it with `IS NULL`, `IS NOT NULL`,
304
+ `coalesce`, or `CASE`.
305
+
306
+ ### Aggregate behavior
307
+
308
+ Aggregates are different because they operate over groups of rows:
309
+ `count(*)` counts rows, `count(x)` counts non-null `x`, and functions
310
+ such as `sum`, `avg`, `min`, and `max` skip null inputs.
311
+
312
+ ```cypher
313
+ MATCH (p:Person)
314
+ RETURN count(*) AS people,
315
+ count(p.email) AS people_with_email,
316
+ avg(p.age) AS average_known_age
317
+ ```
318
+
319
+ ### Filtering after nullable functions
320
+
321
+ `null` is not equal to anything, including itself. When you use
322
+ `TRY_CAST` or a function that can return `null`, filter with `IS NULL`
323
+ or `IS NOT NULL`.
324
+
325
+ ```cypher
326
+ UNWIND $rows AS row
327
+ WITH row, TRY_CAST(row.started_at AS DATETIME) AS started_at
328
+ WHERE started_at IS NOT NULL
329
+ CREATE (:Event {id: row.id, started_at: started_at})
330
+ ```
331
+
332
+ For default values, use `coalesce`:
333
+
334
+ ```cypher
335
+ RETURN coalesce(TRY_CAST($limit AS INTEGER), 100) AS limit
336
+ ```
337
+
338
+ ## Categories
339
+
340
+ | Category | Examples | Reference |
341
+ |---|---|---|
342
+ | **Aggregation** | `count`, `sum`, `collect`, `percentileCont` | [Aggregation](./aggregation.md) |
343
+ | **String** | `string.lower`, `string.words`, `string.count`, `string.normalize` | [String](./string.md) |
344
+ | **Math** | `math.abs`, `math.hypot`, `math.log_base`, `math.random` | [Math](./math.md) |
345
+ | **Number** | `number.format`, `number.to_base`, `number.from_base`, `bits.and` | [Number](./number.md) |
346
+ | **List** | `value.size`, `list.at`, `list.take_last`, `reduce` | [List](./list.md) |
347
+ | **Map** | `map.get`, `map.get_path`, `map.pick`, `map.deep_merge`, `map.entries` | [Map](./map.md) |
348
+ | **Temporal** | `temporal.now`, `temporal.today`, `temporal.between`, `'2024-01-01'::DATE` | [Temporal](./temporal.md) |
349
+ | **Spatial** | `{x: 1, y: 2}::POINT`, `geo.distance` | [Spatial](./spatial.md) |
350
+ | **Vector** | `[1,2,3]::VECTOR<INTEGER>(3)`, `vector.similarity`, `vector.distance`, `vector.norm`, `vector.dimension`, `vector.coordinates` | [Vector](./vectors.md) |
351
+ | **Utility** | `type.of`, `json.path`, `text.distance`, `bytes.base64_encode`, `uuid.new` | [Utility](./utility.md) |
352
+ | **Path** | `path.length`, `path.nodes`, `path.edges` | [Paths](../queries/paths.md) |
353
+
354
+ The category pages are the detailed references. This page explains the
355
+ shared rules that apply across categories.
356
+
357
+ ## Entity introspection
358
+
359
+ | Common alias | Canonical helper | Takes | Returns |
360
+ |---|---|---|---|
361
+ | `id(x)` | `value.id(x)` | node \| relationship | `Int` — internal id |
362
+ | `labels(n)` | `node.labels(n)` | node | `List<String>` |
363
+ | `type(r)` | `edge.type(r)` | relationship | `String` — rel type |
364
+ | `keys(x)` | `value.keys(x)` | node \| rel \| map | `List<String>` |
365
+ | `properties(x)` | `value.properties(x)` | node \| rel \| map | `Map` |
366
+
367
+ ```cypher
368
+ MATCH (u:User)-[r:FOLLOWS]->(v:User)
369
+ RETURN id(u), labels(u), type(r), keys(u), properties(u)
370
+ ```
371
+
372
+ ### Common uses
373
+
374
+ ```cypher
375
+ // Dump every property on a node as a map
376
+ MATCH (u:User {id: $id}) RETURN properties(u)
377
+
378
+ ;// Discover which labels a node carries
379
+ MATCH (n) WHERE id(n) = $raw_id RETURN labels(n)
380
+
381
+ ;// Inspect the type of a matched edge
382
+ MATCH (a)-[r]->(b) RETURN type(r), count(*) ORDER BY count(*) DESC
383
+
384
+ ;// Avoid duplicate pair rows
385
+ MATCH (a)-[:KNOWS]-(b) WHERE id(a) < id(b) RETURN a, b
386
+ ```
387
+
388
+ See [**Graph model → Identity**](../concepts/graph-model.md#identity) for
389
+ why `id()` is opaque.
390
+
391
+ Use aliases when writing familiar Cypher-style queries. Use canonical
392
+ helpers when you want the type of value being inspected to be obvious in
393
+ mixed examples or generated query text.
394
+
395
+ ## Type conversion and checking
396
+
397
+ | Function | Behaviour |
398
+ |---|---|
399
+ | `toString(x)` | any → `String`; `null` → `null` |
400
+ | `toInteger(x)` / `toIntegerOrNull(x)` | `Int`/`Float`/`String`/`Bool` → `Int`; `OrNull` form suppresses conversion errors |
401
+ | `toFloat(x)` / `toFloatOrNull(x)` | `Int`/`Float`/`String` → `Float`; `OrNull` form suppresses conversion errors |
402
+ | `toBoolean(x)` / `toBooleanOrNull(x)` | `Bool`/`String`/`Int` → `Bool`; `OrNull` form suppresses conversion errors |
403
+ | `x::TYPE` | preferred explicit cast syntax |
404
+ | `CAST(x AS TYPE)` | strict cast syntax |
405
+ | `TRY_CAST(x AS TYPE)` | nullable cast; returns `null` on invalid input |
406
+ | `type.of(x)` | name of the value's type, e.g. `"INTEGER"`, `"LIST<T>"` |
407
+ | `coalesce(a, b, …)` | first non-null argument |
408
+ | `temporal.timestamp()` / `timestamp()` | current Unix time in milliseconds |
409
+
410
+ ```cypher
411
+ RETURN toInteger('42'), // 42
412
+ toIntegerOrNull('abc'), // null
413
+ '2024-01-15'::DATE, // DATE
414
+ TRY_CAST('bad date' AS DATE), // null
415
+ toFloat(42), // 42.0
416
+ coalesce(null, null, 'fallback'), // 'fallback'
417
+ type.of(1), // 'INTEGER'
418
+ type.of([1, 2, 3]), // 'LIST<INTEGER>'
419
+ type.of('2024-01-15'::DATE) // 'DATE'
420
+ ```
421
+
422
+ ### coalesce recipes
423
+
424
+ ```cypher
425
+ // Default a missing property
426
+ MATCH (p:Person) RETURN p.name, coalesce(p.nickname, p.name) AS display
427
+
428
+ ;// Cascade through several optional fields
429
+ RETURN coalesce($phone, $email, 'unknown') AS contact
430
+
431
+ ;// Replace null in ordering
432
+ MATCH (p:Person)
433
+ RETURN p.name, coalesce(p.rank, 999999) AS rank_for_sort
434
+ ORDER BY rank_for_sort
435
+ ```
436
+
437
+ For multi-branch logic with arbitrary predicates per branch (not just
438
+ "first non-null"), use [`CASE`](../queries/return-with.md#case-expressions).
439
+
440
+ ### type.of recipes
441
+
442
+ ```cypher
443
+ // Filter a heterogeneous list to numbers only
444
+ MATCH (n)
445
+ WHERE all(x IN n.values WHERE type.of(x) = 'INTEGER')
446
+ RETURN n
447
+
448
+ ;// Group by runtime type
449
+ UNWIND [1, 'two', 3.0, true, null] AS x
450
+ RETURN type.of(x) AS t, count(*) AS n
451
+ ORDER BY t
452
+ ```
453
+
454
+ ### timestamp
455
+
456
+ Wall-clock milliseconds since the Unix epoch.
457
+
458
+ ```cypher
459
+ MERGE (c:Counter {name: 'events'})
460
+ ON CREATE SET c.first_seen = temporal.timestamp()
461
+ SET c.last_seen = temporal.timestamp()
462
+ ```
463
+
464
+ See [Data Types](../data-types/overview.md) for every `type.of` return
465
+ value and for how each type maps between LoraDB and host languages.
466
+
467
+ ### Conversion forms compared
468
+
469
+ All three forms below target the same type system, but they are meant
470
+ for different reading and error-handling styles:
471
+
472
+ ```cypher
473
+ RETURN '2024-01-15'::DATE AS preferred,
474
+ CAST('2024-01-15' AS DATE) AS casted,
475
+ TRY_CAST('not a date' AS DATE) AS nullable
476
+ ```
477
+
478
+ - `value::TYPE` is the preferred documentation style for handwritten
479
+ query text.
480
+ - `CAST(value AS TYPE)` is Cypher cast syntax and useful for query
481
+ generators or users who prefer that form.
482
+ - `TRY_CAST(value AS TYPE)` is the nullable form. It is the right tool
483
+ for imports, user-provided filters, and optional parameters.
484
+
485
+ Legacy helpers such as `toInteger` remain intentionally documented for
486
+ Cypher compatibility and simple scalar parsing. For typed construction
487
+ of `DATE`, `TIME`, `DATETIME`, `LOCAL_DATETIME`, `DURATION`, `POINT`,
488
+ and `VECTOR`, prefer casts.
489
+
490
+ ## Null propagation — the common thread
491
+
492
+ Most functions return `null` when any argument is `null`. A small
493
+ handful don't, so they're worth memorising:
494
+
495
+ - [Aggregates](./aggregation.md) (`count`, `sum`, …) skip null inputs
496
+ (except `count(*)`, which counts rows).
497
+ - `coalesce(a, b, …)` — returns the first non-null argument.
498
+ - `temporal.timestamp()` / `timestamp()`, `math.pi()`, `math.e()`,
499
+ `math.random()` / `random()` —
500
+ take no arguments.
501
+
502
+ Everywhere else, expect `null` in → `null` out. This is what makes
503
+ [`IS NULL` / `IS NOT NULL`](../queries/where.md#null-checks) essential over
504
+ `= null`.
505
+
506
+ ## Quick lookup
507
+
508
+ Finding the right function for a task:
509
+
510
+ | I want to… | Reach for |
511
+ |---|---|
512
+ | Pick the first non-null value | [`coalesce(a, b, …)`](#type-conversion-and-checking) |
513
+ | Branch on arbitrary conditions | [`CASE WHEN … THEN … END`](../queries/return-with.md#case-expressions) |
514
+ | Count rows matching a condition | [`count(CASE WHEN … THEN 1 END)`](./aggregation.md#count) |
515
+ | Concatenate a list into a string | [`reduce`](./list.md#reduce) over `string.split` / `collect` |
516
+ | Current time (ms) | [`temporal.timestamp()`](#timestamp) / `timestamp()` |
517
+ | Current calendar day | [`temporal.today()`](./temporal.md#construction-and-current-time) |
518
+ | Name of a value's type | [`type.of(x)`](#type-conversion-and-checking) |
519
+ | Internal id of a node / rel | [`id(x)`](#entity-introspection) |
520
+ | Total order over temporal values | `<`, `<=`, `>`, `>=` — see [Ordering](../queries/ordering.md) |
521
+ | Cartesian or geodesic distance | [`geo.distance(a, b)`](./spatial.md#geodistance) |
522
+ | Score a VECTOR against a query vector | [`vector.similarity(v, $q)`](../data-types/vectors.md#bounded-similarity-in-0-1) |
523
+ | Signed distance under a metric | [`vector.distance(a, b, EUCLIDEAN)`](../data-types/vectors.md#signed-distance-metrics) |
524
+ | Magnitude of a VECTOR | [`vector.norm(v, EUCLIDEAN)`](../data-types/vectors.md#vector-norms) |
525
+ | Dimension of a VECTOR | [`vector.dimension(v)`](../data-types/vectors.md#introspection) or `value.size(v)` |
526
+ | Convert VECTOR coordinates back to a LIST | [`vector.coordinates(v, FLOAT)` / `vector.coordinates(v, INTEGER)`](../data-types/vectors.md#introspection) |
527
+
528
+ ## Not supported
529
+
530
+ - **Compatibility utility namespaces** — no external utility compatibility layer.
531
+ - **General-purpose procedures** (`CALL db.labels()` etc.) — rejected at
532
+ analysis time. The supported `CALL` surface today is limited to the
533
+ vector and full-text index query procedures documented in
534
+ [Indexes](../queries/indexes.md).
535
+ - **User-defined functions** — no registration surface.
536
+
537
+ Full list in [Limitations](../limitations.md).
538
+
539
+ ## See also
540
+
541
+ - [**Aggregation Functions**](./aggregation.md) — `count`, `collect`, percentiles.
542
+ - [**String**](./string.md), [**Math**](./math.md), [**List**](./list.md) — everyday helpers.
543
+ - [**Temporal**](./temporal.md), [**Spatial**](./spatial.md) — typed domains.
544
+ - [**Data Types Overview**](../data-types/overview.md) — value shapes.
545
+ - [**Queries → Parameters**](../queries/parameters.md) — binding typed values from the host.