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.
Files changed (260) hide show
  1. package/CHANGELOG.md +35 -1
  2. package/README.md +880 -669
  3. package/dist/actions.d.ts +2 -2
  4. package/dist/actions.d.ts.map +1 -1
  5. package/dist/actions.js +1 -1
  6. package/dist/actions.js.map +1 -1
  7. package/dist/ai-promise-db.d.ts +49 -23
  8. package/dist/ai-promise-db.d.ts.map +1 -1
  9. package/dist/ai-promise-db.js +91 -63
  10. package/dist/ai-promise-db.js.map +1 -1
  11. package/dist/authorization.d.ts.map +1 -1
  12. package/dist/authorization.js +38 -30
  13. package/dist/authorization.js.map +1 -1
  14. package/dist/cascade-orchestrator.d.ts +404 -0
  15. package/dist/cascade-orchestrator.d.ts.map +1 -0
  16. package/dist/cascade-orchestrator.js +828 -0
  17. package/dist/cascade-orchestrator.js.map +1 -0
  18. package/dist/cascade-write-strategy.d.ts +584 -0
  19. package/dist/cascade-write-strategy.d.ts.map +1 -0
  20. package/dist/cascade-write-strategy.js +590 -0
  21. package/dist/cascade-write-strategy.js.map +1 -0
  22. package/dist/ch-adapter.d.ts +358 -0
  23. package/dist/ch-adapter.d.ts.map +1 -0
  24. package/dist/ch-adapter.js +929 -0
  25. package/dist/ch-adapter.js.map +1 -0
  26. package/dist/client/index.d.ts +42 -0
  27. package/dist/client/index.d.ts.map +1 -0
  28. package/dist/client/index.js +43 -0
  29. package/dist/client/index.js.map +1 -0
  30. package/dist/client.d.ts +266 -0
  31. package/dist/client.d.ts.map +1 -0
  32. package/dist/client.js +81 -0
  33. package/dist/client.js.map +1 -0
  34. package/dist/constants.d.ts +64 -1
  35. package/dist/constants.d.ts.map +1 -1
  36. package/dist/constants.js +52 -2
  37. package/dist/constants.js.map +1 -1
  38. package/dist/dataloader.d.ts +99 -0
  39. package/dist/dataloader.d.ts.map +1 -0
  40. package/dist/dataloader.js +225 -0
  41. package/dist/dataloader.js.map +1 -0
  42. package/dist/db-provider-port.d.ts +501 -0
  43. package/dist/db-provider-port.d.ts.map +1 -0
  44. package/dist/db-provider-port.js +113 -0
  45. package/dist/db-provider-port.js.map +1 -0
  46. package/dist/digital-objects-provider.d.ts +49 -0
  47. package/dist/digital-objects-provider.d.ts.map +1 -0
  48. package/dist/digital-objects-provider.js +55 -0
  49. package/dist/digital-objects-provider.js.map +1 -0
  50. package/dist/do-sqlite-adapter.d.ts +402 -0
  51. package/dist/do-sqlite-adapter.d.ts.map +1 -0
  52. package/dist/do-sqlite-adapter.js +745 -0
  53. package/dist/do-sqlite-adapter.js.map +1 -0
  54. package/dist/docs-rels/custom-types.d.ts +134 -0
  55. package/dist/docs-rels/custom-types.d.ts.map +1 -0
  56. package/dist/docs-rels/custom-types.js +70 -0
  57. package/dist/docs-rels/custom-types.js.map +1 -0
  58. package/dist/docs-rels/index.d.ts +16 -0
  59. package/dist/docs-rels/index.d.ts.map +1 -0
  60. package/dist/docs-rels/index.js +16 -0
  61. package/dist/docs-rels/index.js.map +1 -0
  62. package/dist/docs-rels/migrations/index.d.ts +30 -0
  63. package/dist/docs-rels/migrations/index.d.ts.map +1 -0
  64. package/dist/docs-rels/migrations/index.js +128 -0
  65. package/dist/docs-rels/migrations/index.js.map +1 -0
  66. package/dist/docs-rels/schema.d.ts +2961 -0
  67. package/dist/docs-rels/schema.d.ts.map +1 -0
  68. package/dist/docs-rels/schema.js +244 -0
  69. package/dist/docs-rels/schema.js.map +1 -0
  70. package/dist/durable-clickhouse.d.ts.map +1 -1
  71. package/dist/durable-clickhouse.js +16 -13
  72. package/dist/durable-clickhouse.js.map +1 -1
  73. package/dist/durable-promise.d.ts.map +1 -1
  74. package/dist/durable-promise.js +34 -15
  75. package/dist/durable-promise.js.map +1 -1
  76. package/dist/errors.d.ts +127 -0
  77. package/dist/errors.d.ts.map +1 -0
  78. package/dist/errors.js +210 -0
  79. package/dist/errors.js.map +1 -0
  80. package/dist/eventbridge.d.ts +117 -0
  81. package/dist/eventbridge.d.ts.map +1 -0
  82. package/dist/eventbridge.js +238 -0
  83. package/dist/eventbridge.js.map +1 -0
  84. package/dist/events.d.ts +2 -2
  85. package/dist/events.d.ts.map +1 -1
  86. package/dist/events.js +1 -1
  87. package/dist/events.js.map +1 -1
  88. package/dist/execution-queue.d.ts.map +1 -1
  89. package/dist/execution-queue.js +4 -5
  90. package/dist/execution-queue.js.map +1 -1
  91. package/dist/index.d.ts +35 -8
  92. package/dist/index.d.ts.map +1 -1
  93. package/dist/index.js +106 -6
  94. package/dist/index.js.map +1 -1
  95. package/dist/linguistic.d.ts +3 -108
  96. package/dist/linguistic.d.ts.map +1 -1
  97. package/dist/linguistic.js +3 -372
  98. package/dist/linguistic.js.map +1 -1
  99. package/dist/logger.d.ts +132 -0
  100. package/dist/logger.d.ts.map +1 -0
  101. package/dist/logger.js +137 -0
  102. package/dist/logger.js.map +1 -0
  103. package/dist/memory-provider.d.ts +128 -0
  104. package/dist/memory-provider.d.ts.map +1 -1
  105. package/dist/memory-provider.js +592 -257
  106. package/dist/memory-provider.js.map +1 -1
  107. package/dist/pg-adapter.d.ts +424 -0
  108. package/dist/pg-adapter.d.ts.map +1 -0
  109. package/dist/pg-adapter.js +921 -0
  110. package/dist/pg-adapter.js.map +1 -0
  111. package/dist/pipelines-iceberg-emitter.d.ts +327 -0
  112. package/dist/pipelines-iceberg-emitter.d.ts.map +1 -0
  113. package/dist/pipelines-iceberg-emitter.js +351 -0
  114. package/dist/pipelines-iceberg-emitter.js.map +1 -0
  115. package/dist/provider-capabilities.d.ts +146 -0
  116. package/dist/provider-capabilities.d.ts.map +1 -0
  117. package/dist/provider-capabilities.js +214 -0
  118. package/dist/provider-capabilities.js.map +1 -0
  119. package/dist/rdb-provider-adapter.d.ts +195 -0
  120. package/dist/rdb-provider-adapter.d.ts.map +1 -0
  121. package/dist/rdb-provider-adapter.js +291 -0
  122. package/dist/rdb-provider-adapter.js.map +1 -0
  123. package/dist/schema/cascade.d.ts +48 -17
  124. package/dist/schema/cascade.d.ts.map +1 -1
  125. package/dist/schema/cascade.js +477 -278
  126. package/dist/schema/cascade.js.map +1 -1
  127. package/dist/schema/definition-caches.d.ts +24 -0
  128. package/dist/schema/definition-caches.d.ts.map +1 -0
  129. package/dist/schema/definition-caches.js +26 -0
  130. package/dist/schema/definition-caches.js.map +1 -0
  131. package/dist/schema/dependency-graph.d.ts +21 -109
  132. package/dist/schema/dependency-graph.d.ts.map +1 -1
  133. package/dist/schema/dependency-graph.js +25 -333
  134. package/dist/schema/dependency-graph.js.map +1 -1
  135. package/dist/schema/diff.d.ts +103 -0
  136. package/dist/schema/diff.d.ts.map +1 -0
  137. package/dist/schema/diff.js +329 -0
  138. package/dist/schema/diff.js.map +1 -0
  139. package/dist/schema/entity-operations.d.ts +99 -0
  140. package/dist/schema/entity-operations.d.ts.map +1 -0
  141. package/dist/schema/entity-operations.js +818 -0
  142. package/dist/schema/entity-operations.js.map +1 -0
  143. package/dist/schema/index.d.ts +28 -34
  144. package/dist/schema/index.d.ts.map +1 -1
  145. package/dist/schema/index.js +454 -521
  146. package/dist/schema/index.js.map +1 -1
  147. package/dist/schema/migration.d.ts +205 -0
  148. package/dist/schema/migration.d.ts.map +1 -0
  149. package/dist/schema/migration.js +327 -0
  150. package/dist/schema/migration.js.map +1 -0
  151. package/dist/schema/nl-query-generator.d.ts +68 -0
  152. package/dist/schema/nl-query-generator.d.ts.map +1 -0
  153. package/dist/schema/nl-query-generator.js +362 -0
  154. package/dist/schema/nl-query-generator.js.map +1 -0
  155. package/dist/schema/nl-query.d.ts +65 -0
  156. package/dist/schema/nl-query.d.ts.map +1 -0
  157. package/dist/schema/nl-query.js +178 -0
  158. package/dist/schema/nl-query.js.map +1 -0
  159. package/dist/schema/parse.d.ts.map +1 -1
  160. package/dist/schema/parse.js +144 -89
  161. package/dist/schema/parse.js.map +1 -1
  162. package/dist/schema/provider.d.ts +37 -0
  163. package/dist/schema/provider.d.ts.map +1 -1
  164. package/dist/schema/provider.js +15 -7
  165. package/dist/schema/provider.js.map +1 -1
  166. package/dist/schema/resolve.d.ts +46 -5
  167. package/dist/schema/resolve.d.ts.map +1 -1
  168. package/dist/schema/resolve.js +237 -95
  169. package/dist/schema/resolve.js.map +1 -1
  170. package/dist/schema/search-utils.d.ts +76 -0
  171. package/dist/schema/search-utils.d.ts.map +1 -0
  172. package/dist/schema/search-utils.js +86 -0
  173. package/dist/schema/search-utils.js.map +1 -0
  174. package/dist/schema/seed.d.ts +53 -0
  175. package/dist/schema/seed.d.ts.map +1 -0
  176. package/dist/schema/seed.js +94 -0
  177. package/dist/schema/seed.js.map +1 -0
  178. package/dist/schema/semantic.d.ts +10 -0
  179. package/dist/schema/semantic.d.ts.map +1 -1
  180. package/dist/schema/semantic.js +192 -86
  181. package/dist/schema/semantic.js.map +1 -1
  182. package/dist/schema/sub-apis.d.ts +52 -0
  183. package/dist/schema/sub-apis.d.ts.map +1 -0
  184. package/dist/schema/sub-apis.js +216 -0
  185. package/dist/schema/sub-apis.js.map +1 -0
  186. package/dist/schema/system-entities.d.ts +42 -0
  187. package/dist/schema/system-entities.d.ts.map +1 -0
  188. package/dist/schema/system-entities.js +101 -0
  189. package/dist/schema/system-entities.js.map +1 -0
  190. package/dist/schema/types.d.ts +91 -9
  191. package/dist/schema/types.d.ts.map +1 -1
  192. package/dist/schema/union-fallback.d.ts.map +1 -1
  193. package/dist/schema/union-fallback.js +21 -15
  194. package/dist/schema/union-fallback.js.map +1 -1
  195. package/dist/schema/value-generators/ai.d.ts +54 -0
  196. package/dist/schema/value-generators/ai.d.ts.map +1 -0
  197. package/dist/schema/value-generators/ai.js +136 -0
  198. package/dist/schema/value-generators/ai.js.map +1 -0
  199. package/dist/schema/value-generators/index.d.ts +126 -0
  200. package/dist/schema/value-generators/index.d.ts.map +1 -0
  201. package/dist/schema/value-generators/index.js +219 -0
  202. package/dist/schema/value-generators/index.js.map +1 -0
  203. package/dist/schema/value-generators/placeholder.d.ts +52 -0
  204. package/dist/schema/value-generators/placeholder.d.ts.map +1 -0
  205. package/dist/schema/value-generators/placeholder.js +328 -0
  206. package/dist/schema/value-generators/placeholder.js.map +1 -0
  207. package/dist/schema/value-generators/types.d.ts +116 -0
  208. package/dist/schema/value-generators/types.d.ts.map +1 -0
  209. package/dist/schema/value-generators/types.js +11 -0
  210. package/dist/schema/value-generators/types.js.map +1 -0
  211. package/dist/schema/version.d.ts +111 -0
  212. package/dist/schema/version.d.ts.map +1 -0
  213. package/dist/schema/version.js +190 -0
  214. package/dist/schema/version.js.map +1 -0
  215. package/dist/schema.d.ts +1095 -24
  216. package/dist/schema.d.ts.map +1 -1
  217. package/dist/schema.js +2852 -40
  218. package/dist/schema.js.map +1 -1
  219. package/dist/semantic-vectors.d.ts +39 -0
  220. package/dist/semantic-vectors.d.ts.map +1 -0
  221. package/dist/semantic-vectors.js +334 -0
  222. package/dist/semantic-vectors.js.map +1 -0
  223. package/dist/semantic.d.ts +29 -1
  224. package/dist/semantic.d.ts.map +1 -1
  225. package/dist/semantic.js +26 -16
  226. package/dist/semantic.js.map +1 -1
  227. package/dist/telemetry.d.ts +128 -0
  228. package/dist/telemetry.d.ts.map +1 -0
  229. package/dist/telemetry.js +305 -0
  230. package/dist/telemetry.js.map +1 -0
  231. package/dist/tests.d.ts.map +1 -1
  232. package/dist/tests.js +30 -22
  233. package/dist/tests.js.map +1 -1
  234. package/dist/type-guards.d.ts +50 -5
  235. package/dist/type-guards.d.ts.map +1 -1
  236. package/dist/type-guards.js +87 -16
  237. package/dist/type-guards.js.map +1 -1
  238. package/dist/types.d.ts +33 -245
  239. package/dist/types.d.ts.map +1 -1
  240. package/dist/types.js +62 -72
  241. package/dist/types.js.map +1 -1
  242. package/dist/validation.d.ts +2 -5
  243. package/dist/validation.d.ts.map +1 -1
  244. package/dist/validation.js +65 -93
  245. package/dist/validation.js.map +1 -1
  246. package/dist/worker/db-provider.d.ts +168 -0
  247. package/dist/worker/db-provider.d.ts.map +1 -0
  248. package/dist/worker/db-provider.js +277 -0
  249. package/dist/worker/db-provider.js.map +1 -0
  250. package/dist/worker/index.d.ts +35 -0
  251. package/dist/worker/index.d.ts.map +1 -0
  252. package/dist/worker/index.js +37 -0
  253. package/dist/worker/index.js.map +1 -0
  254. package/dist/worker.d.ts +779 -0
  255. package/dist/worker.d.ts.map +1 -0
  256. package/dist/worker.js +2786 -0
  257. package/dist/worker.js.map +1 -0
  258. package/package.json +46 -16
  259. package/src/docs-rels/migrations/0001-init.sql +125 -0
  260. 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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"}