@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.
- package/README.md +5 -0
- package/dist/types.d.ts +2 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +1 -0
- package/dist/types.js.map +1 -1
- package/docs/README.md +86 -0
- package/docs/concepts/graph-model.md +270 -0
- package/docs/concepts/nodes.md +285 -0
- package/docs/concepts/properties.md +348 -0
- package/docs/concepts/relationships.md +325 -0
- package/docs/concepts/result-formats.md +183 -0
- package/docs/concepts/schema-free.md +183 -0
- package/docs/cookbook.md +1081 -0
- package/docs/data-types/lists-and-maps.md +406 -0
- package/docs/data-types/overview.md +210 -0
- package/docs/data-types/scalars.md +376 -0
- package/docs/data-types/spatial.md +291 -0
- package/docs/data-types/temporal.md +349 -0
- package/docs/data-types/vectors.md +563 -0
- package/docs/errors.md +183 -0
- package/docs/functions/aggregation.md +372 -0
- package/docs/functions/list.md +522 -0
- package/docs/functions/map.md +207 -0
- package/docs/functions/math.md +421 -0
- package/docs/functions/number.md +197 -0
- package/docs/functions/overview.md +545 -0
- package/docs/functions/spatial.md +384 -0
- package/docs/functions/string.md +502 -0
- package/docs/functions/temporal.md +590 -0
- package/docs/functions/utility.md +137 -0
- package/docs/functions/vectors.md +772 -0
- package/docs/getting-started/installation.md +204 -0
- package/docs/getting-started/node.md +582 -0
- package/docs/getting-started/tutorial.md +334 -0
- package/docs/index.md +203 -0
- package/docs/limitations.md +291 -0
- package/docs/performance.md +219 -0
- package/docs/queries/aggregation.md +520 -0
- package/docs/queries/cheat-sheet.md +302 -0
- package/docs/queries/constraints.md +239 -0
- package/docs/queries/create.md +331 -0
- package/docs/queries/examples.md +453 -0
- package/docs/queries/index.md +169 -0
- package/docs/queries/indexes.md +538 -0
- package/docs/queries/match.md +429 -0
- package/docs/queries/ordering.md +359 -0
- package/docs/queries/parameters.md +328 -0
- package/docs/queries/paths.md +462 -0
- package/docs/queries/return-with.md +500 -0
- package/docs/queries/set-delete.md +369 -0
- package/docs/queries/unwind-merge.md +358 -0
- package/docs/queries/where.md +416 -0
- package/docs/snapshot.md +545 -0
- package/docs/troubleshooting.md +1158 -0
- package/docs/wal.md +570 -0
- package/docs/why.md +273 -0
- 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.
|