@loradb/lora-node 0.36.0 → 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 (53) hide show
  1. package/README.md +5 -0
  2. package/docs/README.md +86 -0
  3. package/docs/concepts/graph-model.md +270 -0
  4. package/docs/concepts/nodes.md +285 -0
  5. package/docs/concepts/properties.md +348 -0
  6. package/docs/concepts/relationships.md +325 -0
  7. package/docs/concepts/result-formats.md +183 -0
  8. package/docs/concepts/schema-free.md +183 -0
  9. package/docs/cookbook.md +1081 -0
  10. package/docs/data-types/lists-and-maps.md +406 -0
  11. package/docs/data-types/overview.md +210 -0
  12. package/docs/data-types/scalars.md +376 -0
  13. package/docs/data-types/spatial.md +291 -0
  14. package/docs/data-types/temporal.md +349 -0
  15. package/docs/data-types/vectors.md +563 -0
  16. package/docs/errors.md +183 -0
  17. package/docs/functions/aggregation.md +372 -0
  18. package/docs/functions/list.md +522 -0
  19. package/docs/functions/map.md +207 -0
  20. package/docs/functions/math.md +421 -0
  21. package/docs/functions/number.md +197 -0
  22. package/docs/functions/overview.md +545 -0
  23. package/docs/functions/spatial.md +384 -0
  24. package/docs/functions/string.md +502 -0
  25. package/docs/functions/temporal.md +590 -0
  26. package/docs/functions/utility.md +137 -0
  27. package/docs/functions/vectors.md +772 -0
  28. package/docs/getting-started/installation.md +204 -0
  29. package/docs/getting-started/node.md +582 -0
  30. package/docs/getting-started/tutorial.md +334 -0
  31. package/docs/index.md +203 -0
  32. package/docs/limitations.md +291 -0
  33. package/docs/performance.md +219 -0
  34. package/docs/queries/aggregation.md +520 -0
  35. package/docs/queries/cheat-sheet.md +302 -0
  36. package/docs/queries/constraints.md +239 -0
  37. package/docs/queries/create.md +331 -0
  38. package/docs/queries/examples.md +453 -0
  39. package/docs/queries/index.md +169 -0
  40. package/docs/queries/indexes.md +538 -0
  41. package/docs/queries/match.md +429 -0
  42. package/docs/queries/ordering.md +359 -0
  43. package/docs/queries/parameters.md +328 -0
  44. package/docs/queries/paths.md +462 -0
  45. package/docs/queries/return-with.md +500 -0
  46. package/docs/queries/set-delete.md +369 -0
  47. package/docs/queries/unwind-merge.md +358 -0
  48. package/docs/queries/where.md +416 -0
  49. package/docs/snapshot.md +545 -0
  50. package/docs/troubleshooting.md +1158 -0
  51. package/docs/wal.md +570 -0
  52. package/docs/why.md +273 -0
  53. package/package.json +13 -14
@@ -0,0 +1,183 @@
1
+ ---
2
+ title: "Query Result Formats"
3
+ description: "The four result shapes LoraDB returns — rows, rowArrays, graph, and combined — with the trade-offs between payload size, client ergonomics, and graph versus tabular access."
4
+ online: "https://loradb.com/docs/concepts/result-formats"
5
+ package: "@loradb/lora-node@0.36.1"
6
+ ---
7
+
8
+ # Query Result Formats
9
+
10
+ Every query returns the same data; the engine can shape it into one
11
+ of four wire formats. The choice is a trade-off between payload size,
12
+ ease of access in host code, and whether you want a row view or a
13
+ graph view.
14
+
15
+ ## The four formats
16
+
17
+ | Format | Shape | Use when… |
18
+ |---|---|---|
19
+ | [`rows`](#rows) | One object per row, keyed by column. | Most app code — each row reads like a record. |
20
+ | [`rowArrays`](#rowarrays) | Columns plus tuple rows. | Wide result sets where keys are repetitive. |
21
+ | [`graph`](#graph) | De-duplicated nodes + relationships. | Rendering a graph — visualisers, diffs. |
22
+ | [`combined`](#combined) | Rows **and** a side graph. | You want both per-row data and the underlying entities. |
23
+
24
+ ## Choosing a format
25
+
26
+ | If your consumer… | Pick |
27
+ |---|---|
28
+ | Reads values by column name | `rows` |
29
+ | Processes many rows with the same columns | `rowArrays` (smaller payload) |
30
+ | Draws a graph of matched entities | `graph` |
31
+ | Needs rows **and** the graph they touched | `combined` |
32
+
33
+ If you don't care: `rows` is the most ergonomic default in host code.
34
+
35
+ ## Setting the format
36
+
37
+ | Transport | How |
38
+ |---|---|
39
+ | Rust / Node / Python / WASM / Go / Ruby | `ExecuteOptions { format }` or per-call option |
40
+ | HTTP | `"format": "rows"` in the `POST /query` body |
41
+
42
+ If omitted, the engine-default is [`graph`](#graph). Bindings may
43
+ override that default for ergonomics — for example, `lora-node` and
44
+ `lora-python` return `rows` unless you ask for another shape.
45
+
46
+ ## `rows`
47
+
48
+ The most natural shape for application code: one JSON object per row,
49
+ keyed by the `RETURN` column name.
50
+
51
+ ### Example
52
+
53
+ For `MATCH (p:Person) RETURN p.name AS name, p.born AS born`:
54
+
55
+ ```json
56
+ {
57
+ "rows": [
58
+ { "name": "Ada", "born": 1815 },
59
+ { "name": "Grace", "born": 1906 }
60
+ ]
61
+ }
62
+ ```
63
+
64
+ ### When to prefer it
65
+
66
+ - You want to iterate with `row.name`, `row["name"]`, etc.
67
+ - Result sets are small-to-medium; the per-row key repetition isn't a
68
+ concern.
69
+
70
+ ## `rowArrays`
71
+
72
+ Columns are listed once; rows are arrays indexed by column position.
73
+
74
+ ### Example
75
+
76
+ ```json
77
+ {
78
+ "columns": ["name", "born"],
79
+ "rows": [
80
+ ["Ada", 1815],
81
+ ["Grace", 1906]
82
+ ]
83
+ }
84
+ ```
85
+
86
+ ### When to prefer it
87
+
88
+ - Large result sets — avoids repeating the column keys per row.
89
+ - You're streaming into a tabular UI that already knows column order.
90
+
91
+ ### Gotcha
92
+
93
+ You index rows by position. A schema change (e.g. reordering `RETURN`
94
+ expressions) breaks downstream code. Prefer `rows` for code that's
95
+ read outside the query author's head.
96
+
97
+ ## `graph`
98
+
99
+ Every matched [node](./nodes.md) and [relationship](./relationships.md),
100
+ de-duplicated, with labels, types, and properties hydrated.
101
+
102
+ ### Example
103
+
104
+ For `MATCH (a:Person)-[r:KNOWS]->(b:Person) RETURN a, r, b`:
105
+
106
+ ```json
107
+ {
108
+ "graph": {
109
+ "nodes": [
110
+ { "id": 1, "labels": ["Person"], "properties": { "name": "Ada" } },
111
+ { "id": 2, "labels": ["Person"], "properties": { "name": "Grace" } }
112
+ ],
113
+ "relationships": [
114
+ { "id": 10, "startId": 1, "endId": 2, "type": "KNOWS", "properties": {} }
115
+ ]
116
+ }
117
+ }
118
+ ```
119
+
120
+ ### When to prefer it
121
+
122
+ - You're rendering the graph in a visualiser.
123
+ - You need every entity the query touched, exactly once, regardless of
124
+ how many rows referenced it.
125
+
126
+ ### Gotcha
127
+
128
+ Scalar projections (`RETURN p.name`) don't contribute new entities to
129
+ the graph — you'll get an empty `nodes` / `relationships` list unless
130
+ the query returns nodes or relationships directly.
131
+
132
+ ## `combined`
133
+
134
+ Rows and a side graph in one payload. Useful when you want both
135
+ per-row results and the backing entities (for example: rows for a
136
+ table, and nodes+edges for a graph preview beside it).
137
+
138
+ ### Example
139
+
140
+ ```json
141
+ {
142
+ "columns": ["a", "r", "b"],
143
+ "data": [
144
+ { "a": { "$node": 1 }, "r": { "$rel": 10 }, "b": { "$node": 2 } }
145
+ ],
146
+ "graph": {
147
+ "nodes": [ /* nodes 1 and 2, as in the `graph` format */ ],
148
+ "relationships": [ /* relationship 10 */ ]
149
+ }
150
+ }
151
+ ```
152
+
153
+ Entities in `data` appear as references (e.g. `{"$node": 1}`); their
154
+ full hydrated form lives in `graph`. This keeps the payload compact
155
+ when the same node appears in many rows.
156
+
157
+ ### When to prefer it
158
+
159
+ - Dual views (table + graph) of the same query.
160
+ - You've got a UI that links a table row to a node on a canvas.
161
+
162
+ ## Typed values in every format
163
+
164
+ Regardless of format, scalar and structured values round-trip through
165
+ the same [shared contract](../data-types/overview.md):
166
+
167
+ - Primitives — `Null`, `Boolean`, `Integer`, `Float`, `String`.
168
+ - [Lists & maps](../data-types/lists-and-maps.md).
169
+ - [Temporal values](../data-types/temporal.md) — tagged with
170
+ `{kind: "date" | "datetime" | …, iso: "…"}`.
171
+ - [Spatial points](../data-types/spatial.md) — tagged with
172
+ `{kind: "point", srid, crs, x, y[, z]}`.
173
+ - Graph values — tagged with `{kind: "node" | "relationship" | "path"}`.
174
+
175
+ Each language binding provides narrow type guards to tell them apart
176
+ (`isNode`, `is_point`, …).
177
+
178
+ ## See also
179
+
180
+ - [Data types overview](../data-types/overview.md) — the value model.
181
+ - [Queries — Overview](../queries/index.md) — clauses and the pipeline.
182
+ - [HTTP API reference](https://loradb.com/docs/api/http) — how `format` is set over HTTP.
183
+ - [Troubleshooting → JSON/result format confusion](../troubleshooting.md#queries-return-empty-results).
@@ -0,0 +1,183 @@
1
+ ---
2
+ title: "Schema-Free Writes and Soft Validation"
3
+ description: "How LoraDB handles schema — labels, relationship types, and property keys spring into existence on write, reads never depend on which names exist — and where validation still applies."
4
+ online: "https://loradb.com/docs/concepts/schema-free"
5
+ package: "@loradb/lora-node@0.36.1"
6
+ ---
7
+
8
+ # Schema-Free Writes and Soft Validation
9
+
10
+ **Writes are permissive, and so are reads.** `CREATE` / `MERGE` /
11
+ `SET` accept any label, relationship type, or property key without a
12
+ `CREATE TABLE` step — names come into existence the first time they're
13
+ written. `MATCH` accepts any name too: a label or relationship type no
14
+ entity carries simply matches nothing, and a missing property key
15
+ yields `null`.
16
+
17
+ That is standard Cypher behaviour, and it keeps answers stable: the same
18
+ query gives the same *kind* of answer on an empty graph, a populated
19
+ one, and one whose last `:Comment` was just deleted or rolled back.
20
+ Whether a query is valid never depends on what data happens to exist.
21
+
22
+ ## What "schema-free" actually means
23
+
24
+ The graph tracks three things as the process runs:
25
+
26
+ - The set of **labels** seen on any node since process start.
27
+ - The set of **relationship types** seen on any relationship.
28
+ - The **property keys** seen on any node or relationship.
29
+
30
+ No declaration, no `ALTER TABLE`, no migration. The first write that
31
+ mentions a new name brings it into existence; subsequent writes reuse
32
+ it.
33
+
34
+ ```cypher
35
+ CREATE (c:Country {name: 'NL', iso: 'NLD'})
36
+ ```
37
+
38
+ On an empty graph, this creates the label `Country` and the property
39
+ keys `name` and `iso`. The next `MATCH (:Country)` will find it.
40
+
41
+ ### Unknown names are not errors
42
+
43
+ A `MATCH` for a label that was **never** created is still a valid
44
+ query — it returns zero rows:
45
+
46
+ ```cypher
47
+ MATCH (u:NeverWritten) RETURN u
48
+ // 0 rows
49
+ ```
50
+
51
+ The flip side: a typo such as `:Persn` also returns zero rows instead of
52
+ failing. Catch those in tests or with a small app-layer list of valid
53
+ labels (see [below](#when-to-add-a-soft-schema-at-the-app-layer)).
54
+
55
+ ## Permissive writes
56
+
57
+ `CREATE`, [`MERGE`](../queries/unwind-merge.md#merge), and
58
+ [`SET`](../queries/set-delete.md) accept any name without complaint.
59
+
60
+ ```cypher
61
+ CREATE (:Spaceship {name: 'Rocinante', crew: 4})
62
+ ;// "Spaceship" was never declared. Fine — it now exists.
63
+
64
+ MATCH (s:Spaceship)
65
+ SET s.engine = 'Epstein drive'
66
+ // Adds a new property key; totally legal.
67
+ ```
68
+
69
+ This is good for quick iteration and bad for safety. Unless you add a
70
+ [constraint](../queries/constraints.md), nothing prevents you from creating
71
+ a second `:Spaceship` with completely different properties, and nothing
72
+ ever stops you from typo-ing `Spaceshi` and polluting the label set.
73
+
74
+ ### Things the engine won't catch without constraints
75
+
76
+ - Two `:Person` nodes with different property sets
77
+ (`{name, born}` vs `{username, dob}`).
78
+ - A property named `email` on one node and `e_mail` on another.
79
+ - A `:FOLLOWS` edge with an `active` property on one and not on
80
+ another.
81
+ - A property value that's an `Integer` in one place and `String` in
82
+ another.
83
+
84
+ If any of these matter, declare [constraints](../queries/constraints.md)
85
+ (existence, uniqueness, key, or property type), enforce them at the
86
+ application layer, or use [`MERGE`](#merge-for-idempotent-writes).
87
+ Differently-named keys such as `email` vs `e_mail` are only ever caught
88
+ at the application layer.
89
+
90
+ ## Lenient reads
91
+
92
+ [`MATCH`](../queries/match.md) does not check label, relationship-type, or
93
+ property-key names against the stored data. The same rules hold on an
94
+ empty graph, a populated one, and after the last entity of a kind was
95
+ deleted, had its label removed, or was rolled back:
96
+
97
+ - A label or relationship type no entity carries matches nothing.
98
+ - A property key an entity doesn't have yields `null` on access. See
99
+ [Properties → missing vs null](./properties.md#missing-vs-null).
100
+ - `OPTIONAL MATCH` over an unknown name keeps the outer row with
101
+ `null`s; `UNION` branches over unknown names contribute no rows.
102
+
103
+ ### Reading back what you wrote
104
+
105
+ ```cypher
106
+ CREATE (:Spaceship {name: 'Rocinante'});
107
+ MATCH (s:Spaceship) RETURN s; // 1 row
108
+ MATCH (s:NeverWritten) RETURN s; // 0 rows — not an error
109
+ ```
110
+
111
+ ## `MERGE` for idempotent writes
112
+
113
+ `MERGE` is the write-side idempotency tool: it matches on the given
114
+ pattern, creating only if missing. Add a uniqueness constraint when you
115
+ also need the database to reject duplicate keys:
116
+
117
+ ```cypher
118
+ MERGE (u:User {email: $email})
119
+ ON CREATE SET u.created = temporal.timestamp()
120
+ ON MATCH SET u.last_seen = temporal.timestamp()
121
+ ```
122
+
123
+ It's an important building block for schema-free writes:
124
+
125
+ - **Safe upsert** — a repeated run won't create duplicates.
126
+ - **Constraint-friendly** — a matching uniqueness constraint rejects
127
+ competing duplicate writes. See [Constraints](../queries/constraints.md).
128
+ - **No index required** — without a supporting index or constraint,
129
+ `MERGE` scans the label/type scope for the key map, which is fine for
130
+ moderate scales. See [Limitations → Storage](../limitations.md#storage).
131
+
132
+ See [MERGE](../queries/unwind-merge.md#merge) for the full reference.
133
+
134
+ ## Runtime type checks
135
+
136
+ Because a property's type is only enforced when written — not when
137
+ declared — you occasionally need to verify it at query time:
138
+
139
+ ```cypher
140
+ MATCH (r:Record)
141
+ WHERE type.of(r.id) = 'INTEGER'
142
+ RETURN r
143
+ ```
144
+
145
+ See [Functions → type conversion and checking](../functions/overview.md#type-conversion-and-checking)
146
+ for `type.of`, `toInteger`, `toString`, and friends.
147
+
148
+ ## Trade-offs at a glance
149
+
150
+ | Property | Traditional schema | LoraDB |
151
+ |---|---|---|
152
+ | Declare up front | Required (`CREATE TABLE`) | Not required |
153
+ | Add a new property | Migration | Just `SET it` |
154
+ | Enforce "every node has X" | Constraint | [Existence constraint](../queries/constraints.md) (`IS NOT NULL`) |
155
+ | Enforce "X is unique" | `UNIQUE` | [Uniqueness constraint](../queries/constraints.md) + `MERGE` on the key |
156
+ | Catch typos in writes | Schema | Code review / tests |
157
+ | Catch typos in reads | Schema | Tests / app-layer name list — unknown names return zero rows |
158
+ | Index lookups | Explicit schema-managed indexes | Optional RANGE/TEXT/POINT/LOOKUP/VECTOR/FULLTEXT indexes for performance and search |
159
+
160
+ ## When to add a "soft schema" at the app layer
161
+
162
+ Schema-free is a tool, not a lifestyle. If your data model stabilises,
163
+ pin it down in host code:
164
+
165
+ - A small module that returns the valid labels / types and fails fast
166
+ on typos.
167
+ - A `create_user` function that's the *only* writer of `:User` nodes
168
+ and always sets the same property keys.
169
+ - A `MERGE` on the business key rather than letting callers fan out
170
+ to different shapes.
171
+
172
+ You lose the "schema" catch-your-typo net. Good architecture puts the
173
+ net back, where it's cheap.
174
+
175
+ ## See also
176
+
177
+ - [Graph data model](./graph-model.md) — nodes, relationships, properties.
178
+ - [MERGE](../queries/unwind-merge.md#merge) — idempotent writes.
179
+ - [Properties](./properties.md) — missing vs null, value typing.
180
+ - [Troubleshooting → Semantic errors](../troubleshooting.md#semantic-errors)
181
+ — what the analyzer still rejects.
182
+ - [Limitations → Storage](../limitations.md#storage) — scoped index and
183
+ constraint coverage.