ai-database 2.1.3 → 2.3.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/CHANGELOG.md +35 -1
- package/README.md +880 -669
- package/dist/actions.d.ts +2 -2
- package/dist/actions.d.ts.map +1 -1
- package/dist/actions.js +1 -1
- package/dist/actions.js.map +1 -1
- package/dist/ai-promise-db.d.ts +49 -23
- package/dist/ai-promise-db.d.ts.map +1 -1
- package/dist/ai-promise-db.js +91 -63
- package/dist/ai-promise-db.js.map +1 -1
- package/dist/authorization.d.ts.map +1 -1
- package/dist/authorization.js +38 -30
- package/dist/authorization.js.map +1 -1
- package/dist/cascade-orchestrator.d.ts +404 -0
- package/dist/cascade-orchestrator.d.ts.map +1 -0
- package/dist/cascade-orchestrator.js +828 -0
- package/dist/cascade-orchestrator.js.map +1 -0
- package/dist/cascade-write-strategy.d.ts +584 -0
- package/dist/cascade-write-strategy.d.ts.map +1 -0
- package/dist/cascade-write-strategy.js +590 -0
- package/dist/cascade-write-strategy.js.map +1 -0
- package/dist/ch-adapter.d.ts +358 -0
- package/dist/ch-adapter.d.ts.map +1 -0
- package/dist/ch-adapter.js +929 -0
- package/dist/ch-adapter.js.map +1 -0
- package/dist/client/index.d.ts +42 -0
- package/dist/client/index.d.ts.map +1 -0
- package/dist/client/index.js +43 -0
- package/dist/client/index.js.map +1 -0
- package/dist/client.d.ts +266 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/client.js +81 -0
- package/dist/client.js.map +1 -0
- package/dist/constants.d.ts +64 -1
- package/dist/constants.d.ts.map +1 -1
- package/dist/constants.js +52 -2
- package/dist/constants.js.map +1 -1
- package/dist/dataloader.d.ts +99 -0
- package/dist/dataloader.d.ts.map +1 -0
- package/dist/dataloader.js +225 -0
- package/dist/dataloader.js.map +1 -0
- package/dist/db-provider-port.d.ts +501 -0
- package/dist/db-provider-port.d.ts.map +1 -0
- package/dist/db-provider-port.js +113 -0
- package/dist/db-provider-port.js.map +1 -0
- package/dist/digital-objects-provider.d.ts +49 -0
- package/dist/digital-objects-provider.d.ts.map +1 -0
- package/dist/digital-objects-provider.js +55 -0
- package/dist/digital-objects-provider.js.map +1 -0
- package/dist/do-sqlite-adapter.d.ts +402 -0
- package/dist/do-sqlite-adapter.d.ts.map +1 -0
- package/dist/do-sqlite-adapter.js +745 -0
- package/dist/do-sqlite-adapter.js.map +1 -0
- package/dist/docs-rels/custom-types.d.ts +134 -0
- package/dist/docs-rels/custom-types.d.ts.map +1 -0
- package/dist/docs-rels/custom-types.js +70 -0
- package/dist/docs-rels/custom-types.js.map +1 -0
- package/dist/docs-rels/index.d.ts +16 -0
- package/dist/docs-rels/index.d.ts.map +1 -0
- package/dist/docs-rels/index.js +16 -0
- package/dist/docs-rels/index.js.map +1 -0
- package/dist/docs-rels/migrations/index.d.ts +30 -0
- package/dist/docs-rels/migrations/index.d.ts.map +1 -0
- package/dist/docs-rels/migrations/index.js +128 -0
- package/dist/docs-rels/migrations/index.js.map +1 -0
- package/dist/docs-rels/schema.d.ts +2961 -0
- package/dist/docs-rels/schema.d.ts.map +1 -0
- package/dist/docs-rels/schema.js +244 -0
- package/dist/docs-rels/schema.js.map +1 -0
- package/dist/durable-clickhouse.d.ts.map +1 -1
- package/dist/durable-clickhouse.js +16 -13
- package/dist/durable-clickhouse.js.map +1 -1
- package/dist/durable-promise.d.ts.map +1 -1
- package/dist/durable-promise.js +34 -15
- package/dist/durable-promise.js.map +1 -1
- package/dist/errors.d.ts +127 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +210 -0
- package/dist/errors.js.map +1 -0
- package/dist/eventbridge.d.ts +117 -0
- package/dist/eventbridge.d.ts.map +1 -0
- package/dist/eventbridge.js +238 -0
- package/dist/eventbridge.js.map +1 -0
- package/dist/events.d.ts +2 -2
- package/dist/events.d.ts.map +1 -1
- package/dist/events.js +1 -1
- package/dist/events.js.map +1 -1
- package/dist/execution-queue.d.ts.map +1 -1
- package/dist/execution-queue.js +4 -5
- package/dist/execution-queue.js.map +1 -1
- package/dist/index.d.ts +35 -8
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +106 -6
- package/dist/index.js.map +1 -1
- package/dist/linguistic.d.ts +3 -108
- package/dist/linguistic.d.ts.map +1 -1
- package/dist/linguistic.js +3 -372
- package/dist/linguistic.js.map +1 -1
- package/dist/logger.d.ts +132 -0
- package/dist/logger.d.ts.map +1 -0
- package/dist/logger.js +137 -0
- package/dist/logger.js.map +1 -0
- package/dist/memory-provider.d.ts +128 -0
- package/dist/memory-provider.d.ts.map +1 -1
- package/dist/memory-provider.js +592 -257
- package/dist/memory-provider.js.map +1 -1
- package/dist/pg-adapter.d.ts +424 -0
- package/dist/pg-adapter.d.ts.map +1 -0
- package/dist/pg-adapter.js +921 -0
- package/dist/pg-adapter.js.map +1 -0
- package/dist/pipelines-iceberg-emitter.d.ts +327 -0
- package/dist/pipelines-iceberg-emitter.d.ts.map +1 -0
- package/dist/pipelines-iceberg-emitter.js +351 -0
- package/dist/pipelines-iceberg-emitter.js.map +1 -0
- package/dist/provider-capabilities.d.ts +146 -0
- package/dist/provider-capabilities.d.ts.map +1 -0
- package/dist/provider-capabilities.js +214 -0
- package/dist/provider-capabilities.js.map +1 -0
- package/dist/rdb-provider-adapter.d.ts +195 -0
- package/dist/rdb-provider-adapter.d.ts.map +1 -0
- package/dist/rdb-provider-adapter.js +291 -0
- package/dist/rdb-provider-adapter.js.map +1 -0
- package/dist/schema/cascade.d.ts +48 -17
- package/dist/schema/cascade.d.ts.map +1 -1
- package/dist/schema/cascade.js +477 -278
- package/dist/schema/cascade.js.map +1 -1
- package/dist/schema/definition-caches.d.ts +24 -0
- package/dist/schema/definition-caches.d.ts.map +1 -0
- package/dist/schema/definition-caches.js +26 -0
- package/dist/schema/definition-caches.js.map +1 -0
- package/dist/schema/dependency-graph.d.ts +21 -109
- package/dist/schema/dependency-graph.d.ts.map +1 -1
- package/dist/schema/dependency-graph.js +25 -333
- package/dist/schema/dependency-graph.js.map +1 -1
- package/dist/schema/diff.d.ts +103 -0
- package/dist/schema/diff.d.ts.map +1 -0
- package/dist/schema/diff.js +329 -0
- package/dist/schema/diff.js.map +1 -0
- package/dist/schema/entity-operations.d.ts +99 -0
- package/dist/schema/entity-operations.d.ts.map +1 -0
- package/dist/schema/entity-operations.js +818 -0
- package/dist/schema/entity-operations.js.map +1 -0
- package/dist/schema/index.d.ts +28 -34
- package/dist/schema/index.d.ts.map +1 -1
- package/dist/schema/index.js +454 -521
- package/dist/schema/index.js.map +1 -1
- package/dist/schema/migration.d.ts +205 -0
- package/dist/schema/migration.d.ts.map +1 -0
- package/dist/schema/migration.js +327 -0
- package/dist/schema/migration.js.map +1 -0
- package/dist/schema/nl-query-generator.d.ts +68 -0
- package/dist/schema/nl-query-generator.d.ts.map +1 -0
- package/dist/schema/nl-query-generator.js +362 -0
- package/dist/schema/nl-query-generator.js.map +1 -0
- package/dist/schema/nl-query.d.ts +65 -0
- package/dist/schema/nl-query.d.ts.map +1 -0
- package/dist/schema/nl-query.js +178 -0
- package/dist/schema/nl-query.js.map +1 -0
- package/dist/schema/parse.d.ts.map +1 -1
- package/dist/schema/parse.js +144 -89
- package/dist/schema/parse.js.map +1 -1
- package/dist/schema/provider.d.ts +37 -0
- package/dist/schema/provider.d.ts.map +1 -1
- package/dist/schema/provider.js +15 -7
- package/dist/schema/provider.js.map +1 -1
- package/dist/schema/resolve.d.ts +46 -5
- package/dist/schema/resolve.d.ts.map +1 -1
- package/dist/schema/resolve.js +237 -95
- package/dist/schema/resolve.js.map +1 -1
- package/dist/schema/search-utils.d.ts +76 -0
- package/dist/schema/search-utils.d.ts.map +1 -0
- package/dist/schema/search-utils.js +86 -0
- package/dist/schema/search-utils.js.map +1 -0
- package/dist/schema/seed.d.ts +53 -0
- package/dist/schema/seed.d.ts.map +1 -0
- package/dist/schema/seed.js +94 -0
- package/dist/schema/seed.js.map +1 -0
- package/dist/schema/semantic.d.ts +10 -0
- package/dist/schema/semantic.d.ts.map +1 -1
- package/dist/schema/semantic.js +192 -86
- package/dist/schema/semantic.js.map +1 -1
- package/dist/schema/sub-apis.d.ts +52 -0
- package/dist/schema/sub-apis.d.ts.map +1 -0
- package/dist/schema/sub-apis.js +216 -0
- package/dist/schema/sub-apis.js.map +1 -0
- package/dist/schema/system-entities.d.ts +42 -0
- package/dist/schema/system-entities.d.ts.map +1 -0
- package/dist/schema/system-entities.js +101 -0
- package/dist/schema/system-entities.js.map +1 -0
- package/dist/schema/types.d.ts +91 -9
- package/dist/schema/types.d.ts.map +1 -1
- package/dist/schema/union-fallback.d.ts.map +1 -1
- package/dist/schema/union-fallback.js +21 -15
- package/dist/schema/union-fallback.js.map +1 -1
- package/dist/schema/value-generators/ai.d.ts +54 -0
- package/dist/schema/value-generators/ai.d.ts.map +1 -0
- package/dist/schema/value-generators/ai.js +136 -0
- package/dist/schema/value-generators/ai.js.map +1 -0
- package/dist/schema/value-generators/index.d.ts +126 -0
- package/dist/schema/value-generators/index.d.ts.map +1 -0
- package/dist/schema/value-generators/index.js +219 -0
- package/dist/schema/value-generators/index.js.map +1 -0
- package/dist/schema/value-generators/placeholder.d.ts +52 -0
- package/dist/schema/value-generators/placeholder.d.ts.map +1 -0
- package/dist/schema/value-generators/placeholder.js +328 -0
- package/dist/schema/value-generators/placeholder.js.map +1 -0
- package/dist/schema/value-generators/types.d.ts +116 -0
- package/dist/schema/value-generators/types.d.ts.map +1 -0
- package/dist/schema/value-generators/types.js +11 -0
- package/dist/schema/value-generators/types.js.map +1 -0
- package/dist/schema/version.d.ts +111 -0
- package/dist/schema/version.d.ts.map +1 -0
- package/dist/schema/version.js +190 -0
- package/dist/schema/version.js.map +1 -0
- package/dist/schema.d.ts +1095 -24
- package/dist/schema.d.ts.map +1 -1
- package/dist/schema.js +2852 -40
- package/dist/schema.js.map +1 -1
- package/dist/semantic-vectors.d.ts +39 -0
- package/dist/semantic-vectors.d.ts.map +1 -0
- package/dist/semantic-vectors.js +334 -0
- package/dist/semantic-vectors.js.map +1 -0
- package/dist/semantic.d.ts +29 -1
- package/dist/semantic.d.ts.map +1 -1
- package/dist/semantic.js +26 -16
- package/dist/semantic.js.map +1 -1
- package/dist/telemetry.d.ts +128 -0
- package/dist/telemetry.d.ts.map +1 -0
- package/dist/telemetry.js +305 -0
- package/dist/telemetry.js.map +1 -0
- package/dist/tests.d.ts.map +1 -1
- package/dist/tests.js +30 -22
- package/dist/tests.js.map +1 -1
- package/dist/type-guards.d.ts +50 -5
- package/dist/type-guards.d.ts.map +1 -1
- package/dist/type-guards.js +87 -16
- package/dist/type-guards.js.map +1 -1
- package/dist/types.d.ts +33 -245
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +62 -72
- package/dist/types.js.map +1 -1
- package/dist/validation.d.ts +2 -5
- package/dist/validation.d.ts.map +1 -1
- package/dist/validation.js +65 -93
- package/dist/validation.js.map +1 -1
- package/dist/worker/db-provider.d.ts +168 -0
- package/dist/worker/db-provider.d.ts.map +1 -0
- package/dist/worker/db-provider.js +277 -0
- package/dist/worker/db-provider.js.map +1 -0
- package/dist/worker/index.d.ts +35 -0
- package/dist/worker/index.d.ts.map +1 -0
- package/dist/worker/index.js +37 -0
- package/dist/worker/index.js.map +1 -0
- package/dist/worker.d.ts +779 -0
- package/dist/worker.d.ts.map +1 -0
- package/dist/worker.js +2786 -0
- package/dist/worker.js.map +1 -0
- package/package.json +46 -16
- package/src/docs-rels/migrations/0001-init.sql +125 -0
- package/LICENSE +0 -21
|
@@ -0,0 +1,358 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ClickHouse DBProvider adapter (Stack A analytics layer)
|
|
3
|
+
*
|
|
4
|
+
* First-class adapter for the analytical leg of Stack A per
|
|
5
|
+
* [ADR-0003](../../../docs/adr/0003-storage-strategy-pg-clickhouse-default.md).
|
|
6
|
+
* Implements the {@link DBProviderPort} surface with:
|
|
7
|
+
*
|
|
8
|
+
* - **Tier 1 (entity CRUD)** against a `things` table backed by a
|
|
9
|
+
* `ReplacingMergeTree` so updates produce a logical upsert at merge time.
|
|
10
|
+
* - **Tier 2 (graph traversal)** via Actions: subject/object/recipient/...
|
|
11
|
+
* queries against an append-only `actions` table.
|
|
12
|
+
* - **Tier 3 (analytics)** declared **first-class** — ClickHouse is the
|
|
13
|
+
* substrate for cross-cascade aggregations, time-series rollups, and
|
|
14
|
+
* large-scan analytical queries (cf. ADR-0003 "Tier 3 first-class on
|
|
15
|
+
* ClickHouse"). `analyticsQuery` is exposed for ad-hoc SQL.
|
|
16
|
+
* - **Tier 4 (vector search)** native via ClickHouse's vector distance
|
|
17
|
+
* functions (`cosineDistance`, `L2Distance`, `dotProduct`) up to
|
|
18
|
+
* ~64,000 dimensions. Embeddings live in a companion `embeddings`
|
|
19
|
+
* table (`ns, thing_id, type, embedding Array(Float32)`) joined to
|
|
20
|
+
* `things`. Callers seed it via {@link ClickHouseProvider.upsertEmbedding}
|
|
21
|
+
* and query via {@link ClickHouseProvider.vectorSearch}. Frame-aware
|
|
22
|
+
* role filtering is deferred to a follow-up refinement bead.
|
|
23
|
+
* - **SVO Action recording** + **Verb registry** declared via
|
|
24
|
+
* `hasActionRecording: true` and `hasVerbRegistry: true`.
|
|
25
|
+
* - **Sharding**: `unsharded` by default (ClickHouse's strength is wide
|
|
26
|
+
* tables on a single cluster). The `ns` column doubles as a partition
|
|
27
|
+
* key for callers that want logical tenant separation; declaring
|
|
28
|
+
* `partitioned-by-tenant` switches the capability flag.
|
|
29
|
+
*
|
|
30
|
+
* ## Cascade write path
|
|
31
|
+
*
|
|
32
|
+
* The cascade-scale write path on ClickHouse is **bulk INSERT via
|
|
33
|
+
* `JSONEachRow` format** — a single HTTP POST per batch carries the full
|
|
34
|
+
* write set. {@link ClickHouseProvider.commitBatch} implements this shape;
|
|
35
|
+
* each batch becomes one HTTP request.
|
|
36
|
+
*
|
|
37
|
+
* ## Driver choice
|
|
38
|
+
*
|
|
39
|
+
* The adapter is HTTP-based and driver-agnostic. It consumes a
|
|
40
|
+
* {@link ClickHouseHttpFetcher} — a function that takes a SQL query plus
|
|
41
|
+
* an optional body and returns the response text. Any HTTP client
|
|
42
|
+
* (`fetch`, `node-fetch`, `undici`, Cloudflare Workers `fetch`) works.
|
|
43
|
+
*
|
|
44
|
+
* For ad-hoc scripting against a ClickHouse Cloud or self-hosted instance,
|
|
45
|
+
* {@link createClickHouseHttpFetcher} wraps a basic-auth fetch call.
|
|
46
|
+
*
|
|
47
|
+
* ## Schema
|
|
48
|
+
*
|
|
49
|
+
* The adapter assumes a database named `aidb` (configurable). DDL:
|
|
50
|
+
*
|
|
51
|
+
* ```sql
|
|
52
|
+
* CREATE DATABASE IF NOT EXISTS aidb;
|
|
53
|
+
*
|
|
54
|
+
* CREATE TABLE IF NOT EXISTS aidb.things (
|
|
55
|
+
* ns String,
|
|
56
|
+
* id String,
|
|
57
|
+
* type String,
|
|
58
|
+
* data String, -- JSON-encoded payload
|
|
59
|
+
* created_at DateTime64(3) DEFAULT now64(3),
|
|
60
|
+
* updated_at DateTime64(3) DEFAULT now64(3),
|
|
61
|
+
* version UInt64 DEFAULT toUnixTimestamp64Milli(now64(3))
|
|
62
|
+
* ) ENGINE = ReplacingMergeTree(version)
|
|
63
|
+
* ORDER BY (ns, type, id);
|
|
64
|
+
*
|
|
65
|
+
* CREATE TABLE IF NOT EXISTS aidb.actions (
|
|
66
|
+
* ns String,
|
|
67
|
+
* id String,
|
|
68
|
+
* verb String,
|
|
69
|
+
* subject String,
|
|
70
|
+
* object String,
|
|
71
|
+
* roles String, -- JSON-encoded role map
|
|
72
|
+
* data String, -- JSON-encoded payload
|
|
73
|
+
* status LowCardinality(String) DEFAULT 'pending',
|
|
74
|
+
* created_at DateTime64(3) DEFAULT now64(3),
|
|
75
|
+
* completed_at Nullable(DateTime64(3))
|
|
76
|
+
* ) ENGINE = MergeTree
|
|
77
|
+
* PARTITION BY toYYYYMM(created_at)
|
|
78
|
+
* ORDER BY (ns, verb, subject, created_at);
|
|
79
|
+
*
|
|
80
|
+
* CREATE TABLE IF NOT EXISTS aidb.verbs (
|
|
81
|
+
* name String,
|
|
82
|
+
* data String,
|
|
83
|
+
* created_at DateTime64(3) DEFAULT now64(3),
|
|
84
|
+
* version UInt64 DEFAULT toUnixTimestamp64Milli(now64(3))
|
|
85
|
+
* ) ENGINE = ReplacingMergeTree(version)
|
|
86
|
+
* ORDER BY name;
|
|
87
|
+
* ```
|
|
88
|
+
*
|
|
89
|
+
* `bootstrapClickHouseSchema(fetcher)` ships the DDL above.
|
|
90
|
+
*
|
|
91
|
+
* @packageDocumentation
|
|
92
|
+
*/
|
|
93
|
+
import type { ListOptions, SearchOptions } from './schema/types.js';
|
|
94
|
+
import type { DBProviderPort, ProviderTierCapabilities, SVOAction, ActionQuery, VerbDefinitionInput, VerbRecord, DBProviderSVO, VectorSearchPort, VectorSearchHit, VectorSimilarityMetric } from './db-provider-port.js';
|
|
95
|
+
/**
|
|
96
|
+
* HTTP-shaped ClickHouse query / insert fetcher.
|
|
97
|
+
*
|
|
98
|
+
* The single function takes a SQL query (URL-encoded into the request) plus
|
|
99
|
+
* an optional body (used for `INSERT ... FORMAT JSONEachRow` payloads) and
|
|
100
|
+
* returns the response text. JSON parsing is performed by the adapter.
|
|
101
|
+
*
|
|
102
|
+
* Implementations may pin a base URL, credentials, and database — the
|
|
103
|
+
* adapter only asks for `(query, body)`.
|
|
104
|
+
*
|
|
105
|
+
* @param query - The SQL query to run. The adapter ALWAYS appends
|
|
106
|
+
* `FORMAT JSON` (for SELECT) or `FORMAT JSONEachRow` (for INSERT) where
|
|
107
|
+
* appropriate before passing in.
|
|
108
|
+
* @param body - Optional HTTP request body (for inserts). When `undefined`,
|
|
109
|
+
* the request is parameterless (the SQL is fully self-contained).
|
|
110
|
+
* @returns Raw response text from ClickHouse.
|
|
111
|
+
*/
|
|
112
|
+
export type ClickHouseHttpFetcher = (query: string, body?: string) => Promise<string>;
|
|
113
|
+
/**
|
|
114
|
+
* Options for {@link createClickHouseHttpFetcher}.
|
|
115
|
+
*/
|
|
116
|
+
export interface ClickHouseHttpFetcherOptions {
|
|
117
|
+
/** Base URL of the ClickHouse HTTP endpoint, e.g. `https://abc.clickhouse.cloud:8443`. */
|
|
118
|
+
url: string;
|
|
119
|
+
/** Username for HTTP basic auth. */
|
|
120
|
+
username?: string;
|
|
121
|
+
/** Password for HTTP basic auth. */
|
|
122
|
+
password?: string;
|
|
123
|
+
/** Database to scope queries to (sent via `database=` query string param). */
|
|
124
|
+
database?: string;
|
|
125
|
+
/** A `fetch`-compatible function. Defaults to global `fetch`. */
|
|
126
|
+
fetchImpl?: typeof fetch;
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Wrap a `fetch`-compatible function into a {@link ClickHouseHttpFetcher}.
|
|
130
|
+
*
|
|
131
|
+
* Sends queries via POST with the SQL as the request body for SELECTs and
|
|
132
|
+
* with the data block as the body when `body` is supplied (insert path).
|
|
133
|
+
* Basic-auth credentials are encoded into the `Authorization` header.
|
|
134
|
+
*
|
|
135
|
+
* @example
|
|
136
|
+
* ```ts
|
|
137
|
+
* import { createClickHouseHttpFetcher, createClickHouseProvider } from 'ai-database'
|
|
138
|
+
*
|
|
139
|
+
* const fetcher = createClickHouseHttpFetcher({
|
|
140
|
+
* url: env.CLICKHOUSE_URL,
|
|
141
|
+
* username: env.CLICKHOUSE_USER,
|
|
142
|
+
* password: env.CLICKHOUSE_PASSWORD,
|
|
143
|
+
* database: 'aidb',
|
|
144
|
+
* })
|
|
145
|
+
* const provider = createClickHouseProvider({
|
|
146
|
+
* fetcher,
|
|
147
|
+
* namespace: 'tenant-9',
|
|
148
|
+
* })
|
|
149
|
+
* ```
|
|
150
|
+
*/
|
|
151
|
+
export declare function createClickHouseHttpFetcher(options: ClickHouseHttpFetcherOptions): ClickHouseHttpFetcher;
|
|
152
|
+
/**
|
|
153
|
+
* Options for {@link createClickHouseProvider}.
|
|
154
|
+
*/
|
|
155
|
+
export interface ClickHouseProviderOptions {
|
|
156
|
+
/** HTTP fetcher (typically constructed via {@link createClickHouseHttpFetcher}). */
|
|
157
|
+
fetcher: ClickHouseHttpFetcher;
|
|
158
|
+
/**
|
|
159
|
+
* Namespace / partition key written into every row.
|
|
160
|
+
*
|
|
161
|
+
* @default 'default'
|
|
162
|
+
*/
|
|
163
|
+
namespace?: string;
|
|
164
|
+
/**
|
|
165
|
+
* ClickHouse database housing the tables. Must already exist (or use
|
|
166
|
+
* {@link bootstrapClickHouseSchema}).
|
|
167
|
+
*
|
|
168
|
+
* @default 'aidb'
|
|
169
|
+
*/
|
|
170
|
+
database?: string;
|
|
171
|
+
/**
|
|
172
|
+
* Sharding model to declare. ClickHouse defaults to `unsharded` because
|
|
173
|
+
* a single cluster handles wide-table analytical queries, but
|
|
174
|
+
* deployments using namespace partitioning may declare
|
|
175
|
+
* `partitioned-by-tenant` to signal the boundary to callers.
|
|
176
|
+
*
|
|
177
|
+
* @default 'unsharded'
|
|
178
|
+
*/
|
|
179
|
+
shardingModel?: 'unsharded' | 'partitioned-by-tenant';
|
|
180
|
+
/**
|
|
181
|
+
* Vector dimensions for the embedding columns. Used by the capability
|
|
182
|
+
* declaration only — the actual vector column shape is defined by the
|
|
183
|
+
* schema DDL.
|
|
184
|
+
*
|
|
185
|
+
* @default 1536
|
|
186
|
+
*/
|
|
187
|
+
vectorDimensions?: number;
|
|
188
|
+
/**
|
|
189
|
+
* Driver name for logs / capability metadata.
|
|
190
|
+
*
|
|
191
|
+
* @default 'clickhouse-http'
|
|
192
|
+
*/
|
|
193
|
+
driver?: 'clickhouse-http' | string;
|
|
194
|
+
}
|
|
195
|
+
/**
|
|
196
|
+
* ClickHouse adapter implementing {@link DBProviderPort} and
|
|
197
|
+
* {@link DBProviderSVO}.
|
|
198
|
+
*/
|
|
199
|
+
export declare class ClickHouseProvider implements DBProviderPort, DBProviderSVO, VectorSearchPort {
|
|
200
|
+
private readonly fetcher;
|
|
201
|
+
private readonly namespace;
|
|
202
|
+
private readonly database;
|
|
203
|
+
private readonly _shardingModel;
|
|
204
|
+
private readonly vectorDimensions;
|
|
205
|
+
private readonly driver;
|
|
206
|
+
constructor(options: ClickHouseProviderOptions);
|
|
207
|
+
/**
|
|
208
|
+
* Tier capability declaration. Declares Tier 3 first-class (CH's
|
|
209
|
+
* strength) and Tier 4 (native vector functions, up to 64,000 dims,
|
|
210
|
+
* cosine/L2/dot). Both `hasActionRecording` and `hasVerbRegistry` are
|
|
211
|
+
* `true` — see the SVO methods on this class.
|
|
212
|
+
*/
|
|
213
|
+
get capabilities(): ProviderTierCapabilities;
|
|
214
|
+
get(type: string, id: string): Promise<Record<string, unknown> | null>;
|
|
215
|
+
list(type: string, options?: ListOptions): Promise<Record<string, unknown>[]>;
|
|
216
|
+
search(type: string, query: string, options?: SearchOptions): Promise<Record<string, unknown>[]>;
|
|
217
|
+
create(type: string, id: string | undefined, data: Record<string, unknown>): Promise<Record<string, unknown>>;
|
|
218
|
+
update(type: string, id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
|
|
219
|
+
delete(type: string, id: string): Promise<boolean>;
|
|
220
|
+
related(type: string, id: string, relation: string): Promise<Record<string, unknown>[]>;
|
|
221
|
+
relate(fromType: string, fromId: string, relation: string, toType: string, toId: string, metadata?: {
|
|
222
|
+
matchMode?: 'exact' | 'fuzzy';
|
|
223
|
+
similarity?: number;
|
|
224
|
+
matchedType?: string;
|
|
225
|
+
}): Promise<void>;
|
|
226
|
+
unrelate(fromType: string, fromId: string, relation: string, toType: string, toId: string): Promise<void>;
|
|
227
|
+
recordAction<T extends Record<string, unknown> = Record<string, unknown>>(input: Omit<SVOAction<T>, 'id' | 'createdAt' | 'status'> & {
|
|
228
|
+
status?: SVOAction['status'];
|
|
229
|
+
}): Promise<SVOAction<T>>;
|
|
230
|
+
queryActions<T extends Record<string, unknown> = Record<string, unknown>>(query?: ActionQuery): Promise<SVOAction<T>[]>;
|
|
231
|
+
defineVerb(def: VerbDefinitionInput): Promise<VerbRecord>;
|
|
232
|
+
getVerb(name: string): Promise<VerbRecord | null>;
|
|
233
|
+
listVerbs(): Promise<VerbRecord[]>;
|
|
234
|
+
/**
|
|
235
|
+
* Bulk-commit Things and Actions in two single-table inserts via
|
|
236
|
+
* `JSONEachRow`. Each table's payload is one HTTP POST, two HTTP
|
|
237
|
+
* requests total per batch. ClickHouse swallows duplicate inserts via
|
|
238
|
+
* the `ReplacingMergeTree` engine on `things` (versioned dedup at merge
|
|
239
|
+
* time) and via append-only writes on `actions` (caller is responsible
|
|
240
|
+
* for deduping ids if needed).
|
|
241
|
+
*
|
|
242
|
+
* Returns the count of rows submitted (CH does not report inserted-row
|
|
243
|
+
* counts via the HTTP interface in a uniform way; the values here
|
|
244
|
+
* reflect the input batch sizes).
|
|
245
|
+
*
|
|
246
|
+
* @example
|
|
247
|
+
* ```ts
|
|
248
|
+
* const { thingsInserted, actionsInserted } = await provider.commitBatch({
|
|
249
|
+
* things: [
|
|
250
|
+
* { type: 'Customer', id: 'c1', data: { name: 'Acme' } },
|
|
251
|
+
* { type: 'Order', id: 'o1', data: { total: 100 } },
|
|
252
|
+
* ],
|
|
253
|
+
* actions: [
|
|
254
|
+
* { id: 'a1', verb: 'placedBy', subject: 'o1', object: 'c1', status: 'completed' },
|
|
255
|
+
* ],
|
|
256
|
+
* })
|
|
257
|
+
* ```
|
|
258
|
+
*/
|
|
259
|
+
commitBatch(input: {
|
|
260
|
+
things?: ReadonlyArray<{
|
|
261
|
+
id: string;
|
|
262
|
+
type: string;
|
|
263
|
+
data: Record<string, unknown>;
|
|
264
|
+
}>;
|
|
265
|
+
actions?: ReadonlyArray<{
|
|
266
|
+
id?: string;
|
|
267
|
+
verb: string;
|
|
268
|
+
subject?: string | undefined;
|
|
269
|
+
object?: string | undefined;
|
|
270
|
+
roles?: Record<string, string> | undefined;
|
|
271
|
+
data?: Record<string, unknown> | undefined;
|
|
272
|
+
status?: SVOAction['status'] | undefined;
|
|
273
|
+
}>;
|
|
274
|
+
}): Promise<{
|
|
275
|
+
thingsInserted: number;
|
|
276
|
+
actionsInserted: number;
|
|
277
|
+
}>;
|
|
278
|
+
/**
|
|
279
|
+
* Pass-through for ad-hoc analytical SQL. Appends `FORMAT JSON` if the
|
|
280
|
+
* caller hasn't specified an output format; the parsed `data` array is
|
|
281
|
+
* returned. Use for time-series rollups, aggregations, or callers that
|
|
282
|
+
* want to reach into ClickHouse without going through the adapter's
|
|
283
|
+
* CRUD surface.
|
|
284
|
+
*
|
|
285
|
+
* Note: parameter substitution is left to the caller (ClickHouse's
|
|
286
|
+
* `query_parameters` HTTP shape varies by version). Pre-format the SQL
|
|
287
|
+
* with `quote()` or use `parametrizeQuery` upstream.
|
|
288
|
+
*/
|
|
289
|
+
analyticsQuery(query: string, _params?: Record<string, unknown>): Promise<Array<Record<string, unknown>>>;
|
|
290
|
+
/**
|
|
291
|
+
* Upsert an embedding for a Thing into the `embeddings` table. Backed by
|
|
292
|
+
* `ReplacingMergeTree(version)` so callers may overwrite an embedding
|
|
293
|
+
* by re-inserting; the higher version wins at merge time.
|
|
294
|
+
*
|
|
295
|
+
* @example
|
|
296
|
+
* ```ts
|
|
297
|
+
* await provider.upsertEmbedding('Document', 'doc-1', new Array(1536).fill(0))
|
|
298
|
+
* ```
|
|
299
|
+
*/
|
|
300
|
+
upsertEmbedding(type: string, id: string, embedding: ReadonlyArray<number>): Promise<void>;
|
|
301
|
+
/**
|
|
302
|
+
* Tier 4 — vector search via ClickHouse native distance functions.
|
|
303
|
+
*
|
|
304
|
+
* Function selection by metric:
|
|
305
|
+
* - `'cosine'` (default): `cosineDistance(embedding, query)` — score is
|
|
306
|
+
* `1 - distance`.
|
|
307
|
+
* - `'l2'`: `L2Distance(embedding, query)` — score is `-distance`.
|
|
308
|
+
* - `'dot'`: `dotProduct(embedding, query)` — score is the inner product
|
|
309
|
+
* directly.
|
|
310
|
+
*
|
|
311
|
+
* Frame-aware role filtering is deferred (see PG adapter doc).
|
|
312
|
+
*/
|
|
313
|
+
vectorSearch<T extends Record<string, unknown> = Record<string, unknown>>(type: string, queryEmbedding: number[], options?: {
|
|
314
|
+
metric?: VectorSimilarityMetric;
|
|
315
|
+
limit?: number;
|
|
316
|
+
minScore?: number;
|
|
317
|
+
}): Promise<VectorSearchHit<T>[]>;
|
|
318
|
+
/**
|
|
319
|
+
* Driver / connection metadata for diagnostics.
|
|
320
|
+
*/
|
|
321
|
+
describe(): {
|
|
322
|
+
adapter: string;
|
|
323
|
+
driver: string;
|
|
324
|
+
namespace: string;
|
|
325
|
+
database: string;
|
|
326
|
+
};
|
|
327
|
+
}
|
|
328
|
+
/**
|
|
329
|
+
* Run the canonical DDL against a ClickHouse fetcher. Idempotent — uses
|
|
330
|
+
* `IF NOT EXISTS` throughout. Designed for one-shot cluster bootstrap and
|
|
331
|
+
* for test harnesses; production deployments typically run schema
|
|
332
|
+
* migrations via a CI tool.
|
|
333
|
+
*/
|
|
334
|
+
export declare function bootstrapClickHouseSchema(fetcher: ClickHouseHttpFetcher, options?: {
|
|
335
|
+
database?: string;
|
|
336
|
+
vectorDimensions?: number;
|
|
337
|
+
}): Promise<void>;
|
|
338
|
+
/**
|
|
339
|
+
* Convenience factory for {@link ClickHouseProvider}.
|
|
340
|
+
*
|
|
341
|
+
* @example
|
|
342
|
+
* ```ts
|
|
343
|
+
* import { createClickHouseProvider, createClickHouseHttpFetcher } from 'ai-database'
|
|
344
|
+
*
|
|
345
|
+
* const fetcher = createClickHouseHttpFetcher({
|
|
346
|
+
* url: env.CLICKHOUSE_URL,
|
|
347
|
+
* username: env.CLICKHOUSE_USER,
|
|
348
|
+
* password: env.CLICKHOUSE_PASSWORD,
|
|
349
|
+
* database: 'aidb',
|
|
350
|
+
* })
|
|
351
|
+
* const provider = createClickHouseProvider({
|
|
352
|
+
* fetcher,
|
|
353
|
+
* namespace: 'tenant-9',
|
|
354
|
+
* })
|
|
355
|
+
* ```
|
|
356
|
+
*/
|
|
357
|
+
export declare function createClickHouseProvider(options: ClickHouseProviderOptions): ClickHouseProvider;
|
|
358
|
+
//# sourceMappingURL=ch-adapter.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"ch-adapter.d.ts","sourceRoot":"","sources":["../src/ch-adapter.ts"],"names":[],"mappings":"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"}
|