datanotes 3.4.2 → 3.5.0
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 +1 -1
- package/dist/api/extensions.cjs +1088 -5
- package/dist/api/extensions.js +1088 -5
- package/dist/api/index.cjs +1088 -5
- package/dist/api/index.js +1088 -5
- package/dist/api/mcp.cjs +1088 -5
- package/dist/api/mcp.js +1088 -5
- package/dist/datanotes.cjs +4408 -1618
- package/dist/docs/administration/git-sync.md +17 -0
- package/dist/docs/administration/limits.md +29 -0
- package/dist/docs/administration/use-with-obsidian.md +12 -0
- package/dist/docs/api/operations/alter_table.md +6 -1
- package/dist/docs/api/operations/create_table.md +5 -0
- package/dist/docs/api/operations/describe_table.md +1 -1
- package/dist/docs/api/operations/pack_rows.md +45 -0
- package/dist/docs/api/operations/tags/auxiliary.md +2 -0
- package/dist/docs/api/operations/unpack_rows.md +40 -0
- package/dist/docs/api.md +3 -1
- package/dist/docs/guides/data-quality/check-constraints.md +10 -10
- package/dist/docs/guides/data-quality/hand-edits.md +8 -8
- package/dist/docs/guides/database-objects/bases.md +11 -11
- package/dist/docs/guides/database-objects/catalogs-and-schemas.md +10 -10
- package/dist/docs/guides/database-objects/columns.md +41 -41
- package/dist/docs/guides/database-objects/packs.md +563 -0
- package/dist/docs/guides/database-objects/relations.md +28 -28
- package/dist/docs/guides/database-objects/tables.md +28 -28
- package/dist/docs/guides/database-objects/views.md +44 -44
- package/dist/docs/guides/history/change-data-feed.md +34 -34
- package/dist/docs/guides/history/journal-and-undo.md +12 -12
- package/dist/docs/guides/history/restore.md +20 -20
- package/dist/docs/guides/history/table-history.md +31 -31
- package/dist/docs/guides/read-and-write/automatic-links.md +15 -15
- package/dist/docs/guides/read-and-write/import-notes.md +21 -21
- package/dist/docs/guides/read-and-write/joins-and-aggregates.md +7 -7
- package/dist/docs/guides/read-and-write/read-and-filter.md +10 -10
- package/dist/docs/guides/read-and-write/write-rows.md +10 -10
- package/dist/docs/guides/search/text.md +1 -1
- package/dist/docs/reference/cli.md +3 -1
- package/dist/docs/reference/operations/auxiliary.md +30 -1
- package/dist/docs/reference/operations/queries.md +1 -1
- package/dist/docs/reference/operations/rows.md +3 -3
- package/dist/docs/reference/operations/schema.md +8 -4
- package/dist/docs/reference/operations.md +55 -53
- package/dist/docs/reference/settings.md +1 -0
- package/dist/docs/release-notes.md +29 -0
- package/package.json +1 -1
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
> Every operation of the HTTP API, offered to agents as an MCP tool of the same name, grouped by kind.
|
|
4
4
|
|
|
5
|
-
The engine has
|
|
5
|
+
The engine has 57 operations of five kinds, like the statements of a SQL reference. The MCP server, `datanotes mcp`, offers each operation as an MCP tool of the same name, and `engineTools()` of `datanotes/mcp` gives the same definitions to [your own MCP server](https://datanotes.dev/develop/build-on-datanotes/#build-your-own-mcp-server). `DatanotesClient.call(name, args)` runs one from code. Over HTTP each one is `POST /datanotes/operations/<name>/`, with its arguments as the JSON body: the [HTTP API reference](https://datanotes.dev/api/) lists them.
|
|
6
6
|
|
|
7
7
|
Next to them, `datanotes mcp` offers three tools that read these docs offline, `list_docs`, `read_docs` and `search_docs`; they aren’t operations of the engine ([Read the docs offline](https://datanotes.dev/guides/agents/docs-offline/)). `search_docs` takes required and excluded words, and becomes a hybrid search when the engine has semantic search on ([Search by words and by meaning](https://datanotes.dev/guides/agents/docs-offline/#search-by-words-and-by-meaning)).
|
|
8
8
|
|
|
@@ -10,58 +10,58 @@ Next to them, `datanotes mcp` offers three tools that read these docs offline, `
|
|
|
10
10
|
|
|
11
11
|
Operations that define the database: tables, columns, constraints, bases and views. [Schema operations (DDL)](https://datanotes.dev/reference/operations/schema/) lists their parameters.
|
|
12
12
|
|
|
13
|
-
| Operation | What it does | Examples
|
|
14
|
-
| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
15
|
-
| [`create_table`](https://datanotes.dev/reference/operations/schema/#create_table) | Create a table: `name`, in `catalog` and `schema` (default: the database’s defaults); the definition goes in metastore.yaml, the rows in `<root>/<catalog>/<schema>/<name>/`. | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/) |
|
|
16
|
-
| [`drop_table`](https://datanotes.dev/reference/operations/schema/#drop_table) | Drop a table. | [Tables](https://datanotes.dev/guides/database-objects/tables/)
|
|
17
|
-
| [`alter_table`](https://datanotes.dev/reference/operations/schema/#alter_table) | Alter a table: move it (`catalog`, `schema`), rename it (`name`), change `partition` / `filename` patterns, `description` (changes, never goes: “” is refused), `aliases`, `exclude` folders, `row_template` (“” removes it), `instructions` (how to fill a row, for agents; “” removes them), `history` (true \| false \| “default”), `autolink_target` (true \| false \| “default”: may automatic links link its rows? default: yes, unless its rows are named by a date or a time) or `tags` (key/value labels merged into the table’s, e.g. | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/) |
|
|
18
|
-
| [`clone_table`](https://datanotes.dev/reference/operations/schema/#clone_table) | CREATE TABLE `target` CLONE `source`: same definition plus independent copies of its rows (deep clone), optionally as of a `version` / `timestamp`. | [Tables](https://datanotes.dev/guides/database-objects/tables/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/)
|
|
19
|
-
| [`add_column`](https://datanotes.dev/reference/operations/schema/#add_column) | Add a typed column. | [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/)
|
|
20
|
-
| [`rename_column`](https://datanotes.dev/reference/operations/schema/#rename_column) | Rename a column in metastore.yaml and on every row. | [Columns and types](https://datanotes.dev/guides/database-objects/columns/)
|
|
21
|
-
| [`drop_column`](https://datanotes.dev/reference/operations/schema/#drop_column) | Remove a column from the schema and every row. | [Columns and types](https://datanotes.dev/guides/database-objects/columns/)
|
|
22
|
-
| [`alter_column`](https://datanotes.dev/reference/operations/schema/#alter_column) | Change a column’s attributes (type, min/max/step, values, required, default, label, aliases, description, note, `ref_where`, `ref_by` (see list_link_targets), `acyclic` (refused while the rows already form a cycle: they are listed); `null` removes an attribute, except `description`, which changes but never goes (null or “” is refused); `dense` true/false). | [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/)
|
|
23
|
-
| [`rename_value`](https://datanotes.dev/reference/operations/schema/#rename_value) | Rename one value of an enum column (e.g. | [Columns and types](https://datanotes.dev/guides/database-objects/columns/)
|
|
24
|
-
| [`comment_on`](https://datanotes.dev/reference/operations/schema/#comment_on) | COMMENT ON CATALOG / SCHEMA: set the `description` of a catalog (`catalog` alone) or of one of its schemas (`catalog` and `schema`) in metastore.yaml: what it holds, so agents pick the right place. | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/)
|
|
25
|
-
| [`define_base`](https://datanotes.dev/reference/operations/schema/#define_base) | Create or replace a base: a named set of columns (same spec as `create_table`) that tables inherit, like a parent class (`bases` in `metastore.yaml`). | [Bases](https://datanotes.dev/guides/database-objects/bases/)
|
|
26
|
-
| [`set_table_bases`](https://datanotes.dev/reference/operations/schema/#set_table_bases) | Set the bases a table inherits from (`bases`, in order; `[]` removes them). | [Bases](https://datanotes.dev/guides/database-objects/bases/)
|
|
27
|
-
| [`add_constraint`](https://datanotes.dev/reference/operations/schema/#add_constraint) | ALTER TABLE ADD CONSTRAINT `name` CHECK: `check` is a where filter every row must match, e.g. | [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/)
|
|
28
|
-
| [`drop_constraint`](https://datanotes.dev/reference/operations/schema/#drop_constraint) | Remove the CHECK constraint `name` from `table`. | [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/)
|
|
29
|
-
| [`create_view`](https://datanotes.dev/reference/operations/schema/#create_view) | Create (or `replace`) a view: a named select stored in metastore.yaml. | [Tables](https://datanotes.dev/guides/database-objects/tables/), [Views](https://datanotes.dev/guides/database-objects/views/)
|
|
30
|
-
| [`drop_view`](https://datanotes.dev/reference/operations/schema/#drop_view) | Remove a view from `metastore.yaml` (undo with `undo_migration`). | [Views](https://datanotes.dev/guides/database-objects/views/)
|
|
13
|
+
| Operation | What it does | Examples |
|
|
14
|
+
| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
15
|
+
| [`create_table`](https://datanotes.dev/reference/operations/schema/#create_table) | Create a table: `name`, in `catalog` and `schema` (default: the database’s defaults); the definition goes in metastore.yaml, the rows in `<root>/<catalog>/<schema>/<name>/`. | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Packs of rows](https://datanotes.dev/guides/database-objects/packs/), [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/) |
|
|
16
|
+
| [`drop_table`](https://datanotes.dev/reference/operations/schema/#drop_table) | Drop a table. | [Tables](https://datanotes.dev/guides/database-objects/tables/) |
|
|
17
|
+
| [`alter_table`](https://datanotes.dev/reference/operations/schema/#alter_table) | Alter a table: move it (`catalog`, `schema`), rename it (`name`), change `partition` / `filename` patterns, `description` (changes, never goes: “” is refused), `aliases`, `exclude` folders, `row_template` (“” removes it), `instructions` (how to fill a row, for agents; “” removes them), `history` (true \| false \| “default”), `autolink_target` (true \| false \| “default”: may automatic links link its rows? default: yes, unless its rows are named by a date or a time) or `tags` (key/value labels merged into the table’s, e.g. | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Packs of rows](https://datanotes.dev/guides/database-objects/packs/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/) |
|
|
18
|
+
| [`clone_table`](https://datanotes.dev/reference/operations/schema/#clone_table) | CREATE TABLE `target` CLONE `source`: same definition plus independent copies of its rows (deep clone), optionally as of a `version` / `timestamp`. | [Tables](https://datanotes.dev/guides/database-objects/tables/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/) |
|
|
19
|
+
| [`add_column`](https://datanotes.dev/reference/operations/schema/#add_column) | Add a typed column. | [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/) |
|
|
20
|
+
| [`rename_column`](https://datanotes.dev/reference/operations/schema/#rename_column) | Rename a column in metastore.yaml and on every row. | [Columns and types](https://datanotes.dev/guides/database-objects/columns/) |
|
|
21
|
+
| [`drop_column`](https://datanotes.dev/reference/operations/schema/#drop_column) | Remove a column from the schema and every row. | [Columns and types](https://datanotes.dev/guides/database-objects/columns/) |
|
|
22
|
+
| [`alter_column`](https://datanotes.dev/reference/operations/schema/#alter_column) | Change a column’s attributes (type, min/max/step, values, required, default, label, aliases, description, note, `ref_where`, `ref_by` (see list_link_targets), `acyclic` (refused while the rows already form a cycle: they are listed); `null` removes an attribute, except `description`, which changes but never goes (null or “” is refused); `dense` true/false). | [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/) |
|
|
23
|
+
| [`rename_value`](https://datanotes.dev/reference/operations/schema/#rename_value) | Rename one value of an enum column (e.g. | [Columns and types](https://datanotes.dev/guides/database-objects/columns/) |
|
|
24
|
+
| [`comment_on`](https://datanotes.dev/reference/operations/schema/#comment_on) | COMMENT ON CATALOG / SCHEMA: set the `description` of a catalog (`catalog` alone) or of one of its schemas (`catalog` and `schema`) in metastore.yaml: what it holds, so agents pick the right place. | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/) |
|
|
25
|
+
| [`define_base`](https://datanotes.dev/reference/operations/schema/#define_base) | Create or replace a base: a named set of columns (same spec as `create_table`) that tables inherit, like a parent class (`bases` in `metastore.yaml`). | [Bases](https://datanotes.dev/guides/database-objects/bases/) |
|
|
26
|
+
| [`set_table_bases`](https://datanotes.dev/reference/operations/schema/#set_table_bases) | Set the bases a table inherits from (`bases`, in order; `[]` removes them). | [Bases](https://datanotes.dev/guides/database-objects/bases/) |
|
|
27
|
+
| [`add_constraint`](https://datanotes.dev/reference/operations/schema/#add_constraint) | ALTER TABLE ADD CONSTRAINT `name` CHECK: `check` is a where filter every row must match, e.g. | [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/) |
|
|
28
|
+
| [`drop_constraint`](https://datanotes.dev/reference/operations/schema/#drop_constraint) | Remove the CHECK constraint `name` from `table`. | [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/) |
|
|
29
|
+
| [`create_view`](https://datanotes.dev/reference/operations/schema/#create_view) | Create (or `replace`) a view: a named select stored in metastore.yaml. | [Tables](https://datanotes.dev/guides/database-objects/tables/), [Views](https://datanotes.dev/guides/database-objects/views/) |
|
|
30
|
+
| [`drop_view`](https://datanotes.dev/reference/operations/schema/#drop_view) | Remove a view from `metastore.yaml` (undo with `undo_migration`). | [Views](https://datanotes.dev/guides/database-objects/views/) |
|
|
31
31
|
|
|
32
32
|
## Rows (DML)
|
|
33
33
|
|
|
34
34
|
Operations that write rows: insert, update, merge, delete, move, adopt and batch. [Row operations (DML)](https://datanotes.dev/reference/operations/rows/) lists their parameters.
|
|
35
35
|
|
|
36
|
-
| Operation | What it does | Examples
|
|
37
|
-
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
38
|
-
| [`insert_row`](https://datanotes.dev/reference/operations/rows/#insert_row) | Insert a row (new note). | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Validation](https://datanotes.dev/guides/data-quality/validation/), [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/), [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Batch writes](https://datanotes.dev/guides/read-and-write/batch/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/), [Journal and undo](https://datanotes.dev/guides/history/journal-and-undo/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/), [Change data feed](https://datanotes.dev/guides/history/change-data-feed/), [Restore a table or the database](https://datanotes.dev/guides/history/restore/) |
|
|
39
|
-
| [`update_row`](https://datanotes.dev/reference/operations/rows/#update_row) | Update exactly ONE row, addressed by its `id` (the system UUID) or its `path`; refused when the row does not exist (or id and path disagree). | [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/), [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Batch writes](https://datanotes.dev/guides/read-and-write/batch/), [Journal and undo](https://datanotes.dev/guides/history/journal-and-undo/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/), [Change data feed](https://datanotes.dev/guides/history/change-data-feed/), [Restore a table or the database](https://datanotes.dev/guides/history/restore/) |
|
|
40
|
-
| [`update_rows`](https://datanotes.dev/reference/operations/rows/#update_rows) | Update every row matching `where` (required: `{}` is every row). | [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/)
|
|
41
|
-
| [`merge_rows`](https://datanotes.dev/reference/operations/rows/#merge_rows) | MERGE (upsert) `rows` into `table` by the key columns `on` (e.g. | [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/)
|
|
42
|
-
| [`delete_rows`](https://datanotes.dev/reference/operations/rows/#delete_rows) | Delete rows matching `where`. | [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/)
|
|
43
|
-
| [`move_rows`](https://datanotes.dev/reference/operations/rows/#move_rows) | Move rows matching `where` (required: `{}` is every row) to another table (e.g. | [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/)
|
|
44
|
-
| [`adopt_rows`](https://datanotes.dev/reference/operations/rows/#adopt_rows) | Turn existing notes (not rows of any table yet) into rows of `table`, keeping their body and links: `rename` keys (`{"data": "occurred_at"}`), `set` for all, `per_row` values by note path (`{"Home/x.md": {"zone": "[[Kitchen]]"}}`), `drop` keys the table does not have. | [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/)
|
|
45
|
-
| [`batch`](https://datanotes.dev/reference/operations/rows/#batch) | Several writes that succeed or fail together. | [Views](https://datanotes.dev/guides/database-objects/views/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/), [Batch writes](https://datanotes.dev/guides/read-and-write/batch/), [Restore a table or the database](https://datanotes.dev/guides/history/restore/) |
|
|
46
|
-
| [`align_relations`](https://datanotes.dev/reference/operations/rows/#align_relations) | Add the reciprocal links missing on a table’s `inverse` link columns (e.g. | [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/)
|
|
47
|
-
| [`recompute_columns`](https://datanotes.dev/reference/operations/rows/#recompute_columns) | Bring generated and identity columns up to date (all rows, or only `paths`), e.g. | [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/)
|
|
36
|
+
| Operation | What it does | Examples |
|
|
37
|
+
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
38
|
+
| [`insert_row`](https://datanotes.dev/reference/operations/rows/#insert_row) | Insert a row (new note). | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Packs of rows](https://datanotes.dev/guides/database-objects/packs/), [Validation](https://datanotes.dev/guides/data-quality/validation/), [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/), [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Batch writes](https://datanotes.dev/guides/read-and-write/batch/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/), [Journal and undo](https://datanotes.dev/guides/history/journal-and-undo/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/), [Change data feed](https://datanotes.dev/guides/history/change-data-feed/), [Restore a table or the database](https://datanotes.dev/guides/history/restore/) |
|
|
39
|
+
| [`update_row`](https://datanotes.dev/reference/operations/rows/#update_row) | Update exactly ONE row, addressed by its `id` (the system UUID) or its `path`; refused when the row does not exist (or id and path disagree). | [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Packs of rows](https://datanotes.dev/guides/database-objects/packs/), [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/), [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Batch writes](https://datanotes.dev/guides/read-and-write/batch/), [Journal and undo](https://datanotes.dev/guides/history/journal-and-undo/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/), [Change data feed](https://datanotes.dev/guides/history/change-data-feed/), [Restore a table or the database](https://datanotes.dev/guides/history/restore/) |
|
|
40
|
+
| [`update_rows`](https://datanotes.dev/reference/operations/rows/#update_rows) | Update every row matching `where` (required: `{}` is every row). | [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/) |
|
|
41
|
+
| [`merge_rows`](https://datanotes.dev/reference/operations/rows/#merge_rows) | MERGE (upsert) `rows` into `table` by the key columns `on` (e.g. | [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/) |
|
|
42
|
+
| [`delete_rows`](https://datanotes.dev/reference/operations/rows/#delete_rows) | Delete rows matching `where`. | [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/) |
|
|
43
|
+
| [`move_rows`](https://datanotes.dev/reference/operations/rows/#move_rows) | Move rows matching `where` (required: `{}` is every row) to another table (e.g. | [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/) |
|
|
44
|
+
| [`adopt_rows`](https://datanotes.dev/reference/operations/rows/#adopt_rows) | Turn existing notes (not rows of any table yet) into rows of `table`, keeping their body and links: `rename` keys (`{"data": "occurred_at"}`), `set` for all, `per_row` values by note path (`{"Home/x.md": {"zone": "[[Kitchen]]"}}`), `drop` keys the table does not have. | [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/) |
|
|
45
|
+
| [`batch`](https://datanotes.dev/reference/operations/rows/#batch) | Several writes that succeed or fail together. | [Views](https://datanotes.dev/guides/database-objects/views/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Packs of rows](https://datanotes.dev/guides/database-objects/packs/), [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/), [Batch writes](https://datanotes.dev/guides/read-and-write/batch/), [Restore a table or the database](https://datanotes.dev/guides/history/restore/) |
|
|
46
|
+
| [`align_relations`](https://datanotes.dev/reference/operations/rows/#align_relations) | Add the reciprocal links missing on a table’s `inverse` link columns (e.g. | [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/) |
|
|
47
|
+
| [`recompute_columns`](https://datanotes.dev/reference/operations/rows/#recompute_columns) | Bring generated and identity columns up to date (all rows, or only `paths`), e.g. | [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/) |
|
|
48
48
|
|
|
49
49
|
## Queries
|
|
50
50
|
|
|
51
51
|
Operations that read rows and notes: select_rows, link targets, text and semantic search, the link graph. [Query operations](https://datanotes.dev/reference/operations/queries/) lists their parameters.
|
|
52
52
|
|
|
53
|
-
| Operation | What it does | Examples
|
|
54
|
-
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
55
|
-
| [`select_rows`](https://datanotes.dev/reference/operations/queries/#select_rows) | Query rows: `{table, total, rows: [{path, ...}]}`. | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Views](https://datanotes.dev/guides/database-objects/views/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Validation](https://datanotes.dev/guides/data-quality/validation/), [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/), [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Read and filter rows](https://datanotes.dev/guides/read-and-write/read-and-filter/), [Joins and aggregates](https://datanotes.dev/guides/read-and-write/joins-and-aggregates/), [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/), [Batch writes](https://datanotes.dev/guides/read-and-write/batch/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/), [Journal and undo](https://datanotes.dev/guides/history/journal-and-undo/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/), [Restore a table or the database](https://datanotes.dev/guides/history/restore/) |
|
|
56
|
-
| [`list_link_targets`](https://datanotes.dev/reference/operations/queries/#list_link_targets) | The rows a link column may point to, for one row: what an agent or a picker offers before writing the link. | [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/)
|
|
57
|
-
| [`read_note`](https://datanotes.dev/reference/operations/queries/#read_note) | Read a note or another file of the vault: `{path, content, front_matter, tags, modified_at, created_at, size}`. | [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/), [Read and search notes](https://datanotes.dev/guides/search/text/)
|
|
58
|
-
| [`list_folder`](https://datanotes.dev/reference/operations/queries/#list_folder) | The direct children of a vault folder: `{folder, folders, files}`, each a vault path, sorted; dot-files and dot-folders are left out. | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/), [Read and search notes](https://datanotes.dev/guides/search/text/)
|
|
59
|
-
| [`search_notes`](https://datanotes.dev/reference/operations/queries/#search_notes) | Plain-text search: every word of `query` must occur, case- and accent-insensitive, in the note’s path or text; there are no operators. | [Read and search notes](https://datanotes.dev/guides/search/text/)
|
|
60
|
-
| [`semantic_search`](https://datanotes.dev/reference/operations/queries/#semantic_search) | Find notes by meaning, not exact words: `{query, results: [{path, score, heading, snippet, table?}]}`, one result per note (its best passage), best first. | [Find notes by meaning](https://datanotes.dev/guides/search/semantic/)
|
|
61
|
-
| [`search`](https://datanotes.dev/reference/operations/queries/#search) | Search the notes by their words and, when semantic search is on, by their meaning: `{query, results: [{path, table?, score, heading, snippet, matched_by}], meaning}`, one result per note, best first. | [Search notes by words and meaning](https://datanotes.dev/guides/search/hybrid/)
|
|
62
|
-
| [`graph_neighbors`](https://datanotes.dev/reference/operations/queries/#graph_neighbors) | Direct neighbours of notes: what they link to (`out`) and what links to them (`in`, backlinks), with counts per edge label. | [Walk the link graph](https://datanotes.dev/guides/search/link-graph/)
|
|
63
|
-
| [`graph_traverse`](https://datanotes.dev/reference/operations/queries/#graph_traverse) | Breadth-first walk over links from `from_nodes` (`{"paths": [...]}`, `{"table", "where"}` and/or `{"tables": [...]}`). | [Walk the link graph](https://datanotes.dev/guides/search/link-graph/)
|
|
64
|
-
| [`graph_path`](https://datanotes.dev/reference/operations/queries/#graph_path) | Shortest chain of links between two sets of notes (each `{"paths": [...]}`, `{"table", "where"}` and/or `{"tables": [...]}`): `found`, `length` and `path`: the steps (`from`, `label`, `direction`, `to`). | [Walk the link graph](https://datanotes.dev/guides/search/link-graph/)
|
|
53
|
+
| Operation | What it does | Examples |
|
|
54
|
+
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
55
|
+
| [`select_rows`](https://datanotes.dev/reference/operations/queries/#select_rows) | Query rows: `{table, total, rows: [{path, ...}]}`. | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Views](https://datanotes.dev/guides/database-objects/views/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Packs of rows](https://datanotes.dev/guides/database-objects/packs/), [Validation](https://datanotes.dev/guides/data-quality/validation/), [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/), [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Read and filter rows](https://datanotes.dev/guides/read-and-write/read-and-filter/), [Joins and aggregates](https://datanotes.dev/guides/read-and-write/joins-and-aggregates/), [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/), [Batch writes](https://datanotes.dev/guides/read-and-write/batch/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/), [Journal and undo](https://datanotes.dev/guides/history/journal-and-undo/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/), [Restore a table or the database](https://datanotes.dev/guides/history/restore/) |
|
|
56
|
+
| [`list_link_targets`](https://datanotes.dev/reference/operations/queries/#list_link_targets) | The rows a link column may point to, for one row: what an agent or a picker offers before writing the link. | [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/) |
|
|
57
|
+
| [`read_note`](https://datanotes.dev/reference/operations/queries/#read_note) | Read a note or another file of the vault: `{path, content, front_matter, tags, modified_at, created_at, size}`. | [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/), [Read and search notes](https://datanotes.dev/guides/search/text/) |
|
|
58
|
+
| [`list_folder`](https://datanotes.dev/reference/operations/queries/#list_folder) | The direct children of a vault folder: `{folder, folders, files}`, each a vault path, sorted; dot-files and dot-folders are left out. | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/), [Read and search notes](https://datanotes.dev/guides/search/text/) |
|
|
59
|
+
| [`search_notes`](https://datanotes.dev/reference/operations/queries/#search_notes) | Plain-text search: every word of `query` must occur, case- and accent-insensitive, in the note’s path or text; there are no operators. | [Read and search notes](https://datanotes.dev/guides/search/text/) |
|
|
60
|
+
| [`semantic_search`](https://datanotes.dev/reference/operations/queries/#semantic_search) | Find notes by meaning, not exact words: `{query, results: [{path, score, heading, snippet, table?}]}`, one result per note (its best passage), best first. | [Find notes by meaning](https://datanotes.dev/guides/search/semantic/) |
|
|
61
|
+
| [`search`](https://datanotes.dev/reference/operations/queries/#search) | Search the notes by their words and, when semantic search is on, by their meaning: `{query, results: [{path, table?, score, heading, snippet, matched_by}], meaning}`, one result per note, best first. | [Search notes by words and meaning](https://datanotes.dev/guides/search/hybrid/) |
|
|
62
|
+
| [`graph_neighbors`](https://datanotes.dev/reference/operations/queries/#graph_neighbors) | Direct neighbours of notes: what they link to (`out`) and what links to them (`in`, backlinks), with counts per edge label. | [Walk the link graph](https://datanotes.dev/guides/search/link-graph/) |
|
|
63
|
+
| [`graph_traverse`](https://datanotes.dev/reference/operations/queries/#graph_traverse) | Breadth-first walk over links from `from_nodes` (`{"paths": [...]}`, `{"table", "where"}` and/or `{"tables": [...]}`). | [Walk the link graph](https://datanotes.dev/guides/search/link-graph/) |
|
|
64
|
+
| [`graph_path`](https://datanotes.dev/reference/operations/queries/#graph_path) | Shortest chain of links between two sets of notes (each `{"paths": [...]}`, `{"table", "where"}` and/or `{"tables": [...]}`): `found`, `length` and `path`: the steps (`from`, `label`, `direction`, `to`). | [Walk the link graph](https://datanotes.dev/guides/search/link-graph/) |
|
|
65
65
|
|
|
66
66
|
## History
|
|
67
67
|
|
|
@@ -85,13 +85,15 @@ Operations on the journal, a table’s versions, the change feed and webhooks: u
|
|
|
85
85
|
|
|
86
86
|
Operations that describe and check the database, configure it and maintain its indexes. [Auxiliary operations](https://datanotes.dev/reference/operations/auxiliary/) lists their parameters.
|
|
87
87
|
|
|
88
|
-
| Operation | What it does
|
|
89
|
-
| ------------------------------------------------------------------------------------- |
|
|
90
|
-
| [`list_tables`](https://datanotes.dev/reference/operations/auxiliary/#list_tables) | List every table: `name`, `catalog`, `schema`, `qualified` (`personal.metrics.mood` — use it wherever a table is expected; `metrics.mood` or `mood` also work when unambiguous), `path` and, when declared, `description`, `aliases` (other words for what it records) and `tags`.
|
|
91
|
-
| [`describe_table`](https://datanotes.dev/reference/operations/auxiliary/#describe_table) | Describe a table (`catalog.schema.table` or a shorter unambiguous name): `qualified`, `name`, `catalog`, `schema`, `description`, `aliases`, `layout` (`folder`, `row_folder`: the folder pattern of new rows, `archive`), `options` (`partition`, `filename`, `archive`, `exclude`), typed `columns` with label/aliases/description and the dense flag, `untyped_fields`, `row_count`, and when set: `tags`, `bases` (the bases it inherits from, in order), `constraints` (its CHECKs, name → where), `constraint_hints` (their own hints, name → hint), `instructions` (how to fill a row: follow them before you write one), `row_template`, `history`, `autolink_target`, `fields` (their values). | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/) |
|
|
92
|
-
| [`describe_database`](https://datanotes.dev/reference/operations/auxiliary/#describe_database) | Describe the database: its folder (`root`), `metastore` (`metastore.yaml`: read it freely, but it is read-only for agents and changes only through the schema operations), configuration (default catalog and schema, row partition and file-name formats, archive folder, time zone, history, automatic links), journal folder, `bases` (shared column sets and the tables using them), `catalogs` → `schemas` → `tables` (with `row_count`, `tags`, and `unreadable_count` when some rows’ front matter cannot be read) and `views`; catalogs and schemas show their `comment` (set with `comment_on`).
|
|
93
|
-
| [`configure_database`](https://datanotes.dev/reference/operations/auxiliary/#configure_database) | Configure the database (persisted in metastore.yaml `config:`): `root` (rename the database folder; links follow; revert by renaming back), `default_catalog`, `default_schema`, `default_partition` (“” = flat) and `default_filename` (date formats for new time-based tables), `archive_folder`, `timezone` (IANA; completes date-times written without offset), `history` (transaction log for every table: true in a database the engine creates, false when `config` lacks it, as in a metastore from before 3.0.0; change it only on the user’s request), `autolink` (the text a write puts in a body links the notes it mentions; on by default).
|
|
94
|
-
| [`check_table`](https://datanotes.dev/reference/operations/auxiliary/#check_table) | Validate every row against the table (required, types, ranges, enums, links, unknown columns, CHECK constraints, those that follow links included, filtered link targets (ref_where / ref_by), stale generated/identity values, missing inverse links, cycles of hierarchy and acyclic columns, front matter that cannot be read: code `unreadable`, with no column, for a note whose `table` line names the table but whose YAML is broken, which every other read leaves out).
|
|
95
|
-
| [`infer_table`](https://datanotes.dev/reference/operations/auxiliary/#infer_table) | Read-only schema inference from notes’ front matter.
|
|
96
|
-
| [`describe_semantic_index`](https://datanotes.dev/reference/operations/auxiliary/#describe_semantic_index) | The semantic search index: `enabled`, `provider`, `model`, `files`, `passages`, `pending`, `running`, `last_sync`, `last_error`.
|
|
97
|
-
| [`sync_semantic_index`](https://datanotes.dev/reference/operations/auxiliary/#sync_semantic_index) | Bring the semantic search index up to date: embed the notes changed since the last run (the engine also does it on its own about ten seconds after edits).
|
|
88
|
+
| Operation | What it does | Examples |
|
|
89
|
+
| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
90
|
+
| [`list_tables`](https://datanotes.dev/reference/operations/auxiliary/#list_tables) | List every table: `name`, `catalog`, `schema`, `qualified` (`personal.metrics.mood` — use it wherever a table is expected; `metrics.mood` or `mood` also work when unambiguous), `path` and, when declared, `description`, `aliases` (other words for what it records) and `tags`. | [Tables](https://datanotes.dev/guides/database-objects/tables/), [Views](https://datanotes.dev/guides/database-objects/views/) |
|
|
91
|
+
| [`describe_table`](https://datanotes.dev/reference/operations/auxiliary/#describe_table) | Describe a table (`catalog.schema.table` or a shorter unambiguous name): `qualified`, `name`, `catalog`, `schema`, `description`, `aliases`, `layout` (`folder`, `row_folder`: the folder pattern of new rows, `archive`), `options` (`partition`, `filename`, `archive`, `exclude`, `pack`, `pack_after_days`), typed `columns` with label/aliases/description and the dense flag, `untyped_fields`, `row_count`, and when set: `tags`, `bases` (the bases it inherits from, in order), `constraints` (its CHECKs, name → where), `constraint_hints` (their own hints, name → hint), `instructions` (how to fill a row: follow them before you write one), `row_template`, `history`, `autolink_target`, `fields` (their values). | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/) |
|
|
92
|
+
| [`describe_database`](https://datanotes.dev/reference/operations/auxiliary/#describe_database) | Describe the database: its folder (`root`), `metastore` (`metastore.yaml`: read it freely, but it is read-only for agents and changes only through the schema operations), configuration (default catalog and schema, row partition and file-name formats, archive folder, time zone, history, automatic links), journal folder, `bases` (shared column sets and the tables using them), `catalogs` → `schemas` → `tables` (with `row_count`, `tags`, and `unreadable_count` when some rows’ front matter cannot be read) and `views`; catalogs and schemas show their `comment` (set with `comment_on`). | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/) |
|
|
93
|
+
| [`configure_database`](https://datanotes.dev/reference/operations/auxiliary/#configure_database) | Configure the database (persisted in metastore.yaml `config:`): `root` (rename the database folder; links follow; revert by renaming back), `default_catalog`, `default_schema`, `default_partition` (“” = flat) and `default_filename` (date formats for new time-based tables), `archive_folder`, `timezone` (IANA; completes date-times written without offset), `history` (transaction log for every table: true in a database the engine creates, false when `config` lacks it, as in a metastore from before 3.0.0; change it only on the user’s request), `autolink` (the text a write puts in a body links the notes it mentions; on by default). | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/) |
|
|
94
|
+
| [`check_table`](https://datanotes.dev/reference/operations/auxiliary/#check_table) | Validate every row against the table (required, types, ranges, enums, links, unknown columns, CHECK constraints, those that follow links included, filtered link targets (ref_where / ref_by), stale generated/identity values, missing inverse links, cycles of hierarchy and acyclic columns, front matter that cannot be read: code `unreadable`, with no column, for a note whose `table` line names the table but whose YAML is broken, which every other read leaves out). | [Tables](https://datanotes.dev/guides/database-objects/tables/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Find rows that break the schema](https://datanotes.dev/guides/data-quality/check-table/) |
|
|
95
|
+
| [`infer_table`](https://datanotes.dev/reference/operations/auxiliary/#infer_table) | Read-only schema inference from notes’ front matter. | [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/) |
|
|
96
|
+
| [`describe_semantic_index`](https://datanotes.dev/reference/operations/auxiliary/#describe_semantic_index) | The semantic search index: `enabled`, `provider`, `model`, `files`, `passages`, `pending`, `running`, `last_sync`, `last_error`. | [Find notes by meaning](https://datanotes.dev/guides/search/semantic/) |
|
|
97
|
+
| [`sync_semantic_index`](https://datanotes.dev/reference/operations/auxiliary/#sync_semantic_index) | Bring the semantic search index up to date: embed the notes changed since the last run (the engine also does it on its own about ten seconds after edits). | [Find notes by meaning](https://datanotes.dev/guides/search/semantic/) |
|
|
98
|
+
| [`pack_rows`](https://datanotes.dev/reference/operations/auxiliary/#pack_rows) | Put the rows of a table’s closed periods into packs: one note per period (`<table> <key>.md` in the table’s folder), a `##` section per row, `key:: value` lines for its values. | [Packs of rows](https://datanotes.dev/guides/database-objects/packs/) |
|
|
99
|
+
| [`unpack_rows`](https://datanotes.dev/reference/operations/auxiliary/#unpack_rows) | Take rows out of their packs as notes of their own, at their paths, with the text and the modification time they had (the opposite of pack_rows): every pack of the table, the pack of `key`, or only the rows `where` matches (as select_rows filters). | [Packs of rows](https://datanotes.dev/guides/database-objects/packs/) |
|
|
@@ -21,6 +21,7 @@ The headless engine reads `settings.json` in its store, outside the vault (`data
|
|
|
21
21
|
| `telemetrySlowSpanMs` | `0` | A request, operation or background job lasting at least this many milliseconds is also logged as a WARN (0: never). |
|
|
22
22
|
| `telemetryEnvironment` | `""` | `deployment.environment.name` of the logs and traces, such as `dev` or `home` (empty: none). |
|
|
23
23
|
| `autoRecompute` | `true` | After a row is edited by hand, recompute its generated / identity columns (a few seconds after the last change, as a journaled `recompute_columns` operation). |
|
|
24
|
+
| `autoPack` | `true` | Once a day, after 10 minutes without writes, put the rows of closed periods into packs (`pack_rows` on every table with a `pack` option; the engine service only). Off: tables are packed only by `pack_rows`. |
|
|
24
25
|
| `repairLinksOnHandMove` | `true` | Rewrite the links to a note renamed or moved by hand (in a file manager, with git or a sync tool), across the vault, once the vault has been quiet for 4 s and not while git pulls, rebases or merges. The repair is one journaled `repair_links` operation that undo takes back. Links an editor already rewrote stay as they are. |
|
|
25
26
|
| `semanticEnabled` | `false` | Semantic search: embed notes with `semanticProvider` (off by default: content is sent to it). |
|
|
26
27
|
| `semanticProvider` | `"ollama"` | Embedding provider: `ollama`, `lmstudio`, `openrouter`, `openai` or `custom` (any OpenAI-compatible API). |
|
|
@@ -4,6 +4,35 @@
|
|
|
4
4
|
|
|
5
5
|
This page lists each version of Datanotes, newest first. Datanotes follows [semantic versioning](https://semver.org): a major version can break what you rely on, and its notes list those changes first. The package is on [npm](https://www.npmjs.com/package/datanotes), and each version has a [GitHub release](https://github.com/davidefornelli/datanotes/releases).
|
|
6
6
|
|
|
7
|
+
## 3.5.0
|
|
8
|
+
|
|
9
|
+
Datanotes 3.5.0 brings packs of rows: one note holds the rows of a closed period, such as a month, one `##` section per row. A table with thousands of small rows a year keeps a few files instead of thousands. The engine still sees one row at a time. It only adds to 3.4: no operation, argument or setting goes away, and a table without the new option works as before.
|
|
10
|
+
|
|
11
|
+
### Packs of rows
|
|
12
|
+
|
|
13
|
+
[Packs of rows](https://datanotes.dev/guides/database-objects/packs/) explains the format, the rules and who reads the files.
|
|
14
|
+
|
|
15
|
+
* **`pack` and `pack_after_days`**: two new options of `create_table` and `alter_table`. `pack` is a template of a date or date-time column, such as `"{started_at:YYYY-MM}"`. `pack_after_days` sets how many days after the end of a period its rows wait, 7 by default. `describe_table` shows both in `options`.
|
|
16
|
+
* **`pack_rows`**: a new operation. It puts the rows of every closed period into their pack. A dry run lists the packs and the rows that stay notes of their own, with the reason.
|
|
17
|
+
* **`unpack_rows`**: a new operation. It takes rows out again, as notes of their own, byte for byte, with their modification time.
|
|
18
|
+
* **Silent for the rows**: each row keeps its id, path, values, text and `file_modified`. The change feed, the webhooks and the table’s history see no change.
|
|
19
|
+
* **Writes**: a write to a packed row changes its section. A row whose new values move it to another period comes out as a note of its own.
|
|
20
|
+
* **Hand edits**: the engine compares a pack changed by hand with what it had, by `id`. Only the rows that changed get an event.
|
|
21
|
+
* **Links**: a link to a packed row is `[[pack#row]]`, which Obsidian follows too. `pack_rows` and `unpack_rows` rewrite the links of other notes, and a link column takes the new form.
|
|
22
|
+
* **Journaled**: `undo_migration` takes a pack apart, or packs the rows again.
|
|
23
|
+
* **`autoPack`**: a new setting, on by default. Once a day, after 10 minutes without writes, the engine runs `pack_rows` on every table with a `pack` option.
|
|
24
|
+
* **Engine service only**: Obsidian’s plugin refuses the `pack` option.
|
|
25
|
+
|
|
26
|
+
### Git
|
|
27
|
+
|
|
28
|
+
* **`datanotes pack-merge`**: a new command, a git merge driver. It merges a pack changed on two devices row by row, by `id`, so a conflict stays in the one row changed on both sides.
|
|
29
|
+
* **Git sync registers it**: `--git-sync` sets `merge.datanotes-pack.driver` in the repository and adds `*.md merge=datanotes-pack` to the vault’s `.gitattributes`. [Merge packs row by row](https://datanotes.dev/administration/git-sync/#merge-packs-row-by-row) explains it.
|
|
30
|
+
|
|
31
|
+
### Before you set `pack` on a table
|
|
32
|
+
|
|
33
|
+
* **Check who reads its files**: Obsidian, scripts that count or open the table’s files, and agents with a shell see the packs, not one file per row. Programs that go through the engine see no difference.
|
|
34
|
+
* **Change the layout first**: while rows are in packs, `alter_table` refuses to rename or move the table and to change its `partition`, `filename` or `pack`. Run `unpack_rows` first.
|
|
35
|
+
|
|
7
36
|
## 3.4.2
|
|
8
37
|
|
|
9
38
|
Datanotes 3.4.2 fixes the install of an extension on columns you mapped. It only adds to 3.4: no operation, argument or setting goes away.
|
package/package.json
CHANGED