@lancedb/lancedb 0.41.0-beta.8 → 0.42.0-beta.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/dist/expr.d.ts ADDED
@@ -0,0 +1,64 @@
1
+ import { Expr as NativeExpr } from "./native.js";
2
+ export { Expr as NativeExpr } from "./native";
3
+ /** Values accepted by expression operators. */
4
+ export type ExprLike = Expr | string | number | boolean;
5
+ /**
6
+ * A SQL expression backed by the shared LanceDB expression builder.
7
+ *
8
+ * @example
9
+ * ```ts
10
+ * table.query().where(col("firstName").eq("Alice")).toArray();
11
+ * ```
12
+ */
13
+ export declare class Expr {
14
+ inner: NativeExpr;
15
+ constructor(inner: NativeExpr);
16
+ /** Compare for equality. */
17
+ eq(other: ExprLike): Expr;
18
+ /** Compare for inequality. */
19
+ ne(other: ExprLike): Expr;
20
+ /** Compare for less than. */
21
+ lt(other: ExprLike): Expr;
22
+ /** Compare for less than or equal to. */
23
+ lte(other: ExprLike): Expr;
24
+ /** Compare for greater than. */
25
+ gt(other: ExprLike): Expr;
26
+ /** Compare for greater than or equal to. */
27
+ gte(other: ExprLike): Expr;
28
+ /** Combine two predicates with AND. */
29
+ and(other: Expr): Expr;
30
+ /** Combine two predicates with OR. */
31
+ or(other: Expr): Expr;
32
+ /** Negate this predicate. */
33
+ not(): Expr;
34
+ /** Add a value. */
35
+ add(other: ExprLike): Expr;
36
+ /** Subtract a value. */
37
+ sub(other: ExprLike): Expr;
38
+ /** Multiply by a value. */
39
+ mul(other: ExprLike): Expr;
40
+ /** Divide by a value. */
41
+ div(other: ExprLike): Expr;
42
+ /** Convert a string to lowercase. */
43
+ lower(): Expr;
44
+ /** Convert a string to uppercase. */
45
+ upper(): Expr;
46
+ /** Test whether a string contains a substring. */
47
+ contains(substr: ExprLike): Expr;
48
+ /** Test membership in a list of values. */
49
+ isIn(values: ExprLike[]): Expr;
50
+ /** Cast to an Arrow data type, such as "Int64". */
51
+ cast(dataType: string): Expr;
52
+ /** Serialize with the LanceDB SQL dialect, preserving column case. */
53
+ toSql(): string;
54
+ }
55
+ /** Reference a column by its exact, case-sensitive name. */
56
+ export declare function col(name: string): Expr;
57
+ /** Create a string or numeric literal. Unsafe integers are represented as Float64. */
58
+ export declare function lit(value: string | number): Expr;
59
+ /** Create a boolean literal. */
60
+ export declare function litBool(value: boolean): Expr;
61
+ /** Create an Int64 literal from a JavaScript safe integer. Other numbers throw RangeError. */
62
+ export declare function litInt(value: number): Expr;
63
+ /** Call a registered SQL function, such as `func("lower", col("firstName"))`. */
64
+ export declare function func(name: string, ...args: ExprLike[]): Expr;
package/dist/expr.js ADDED
@@ -0,0 +1,148 @@
1
+ "use strict";
2
+ // SPDX-License-Identifier: Apache-2.0
3
+ // SPDX-FileCopyrightText: Copyright The LanceDB Authors
4
+ Object.defineProperty(exports, "__esModule", { value: true });
5
+ exports.Expr = exports.NativeExpr = void 0;
6
+ exports.col = col;
7
+ exports.lit = lit;
8
+ exports.litBool = litBool;
9
+ exports.litInt = litInt;
10
+ exports.func = func;
11
+ const native_js_1 = require("./native.js");
12
+ var native_1 = require("./native");
13
+ Object.defineProperty(exports, "NativeExpr", { enumerable: true, get: function () { return native_1.Expr; } });
14
+ function coerce(value) {
15
+ if (value instanceof Expr) {
16
+ return value;
17
+ }
18
+ if (typeof value === "string") {
19
+ return lit(value);
20
+ }
21
+ if (typeof value === "boolean") {
22
+ return litBool(value);
23
+ }
24
+ if (typeof value === "number") {
25
+ return lit(value);
26
+ }
27
+ throw new TypeError(`Unsupported literal type: ${typeof value}`);
28
+ }
29
+ /**
30
+ * A SQL expression backed by the shared LanceDB expression builder.
31
+ *
32
+ * @example
33
+ * ```ts
34
+ * table.query().where(col("firstName").eq("Alice")).toArray();
35
+ * ```
36
+ */
37
+ class Expr {
38
+ inner;
39
+ constructor(inner) {
40
+ this.inner = inner;
41
+ }
42
+ /** Compare for equality. */
43
+ eq(other) {
44
+ return new Expr(this.inner.eq(coerce(other).inner));
45
+ }
46
+ /** Compare for inequality. */
47
+ ne(other) {
48
+ return new Expr(this.inner.ne(coerce(other).inner));
49
+ }
50
+ /** Compare for less than. */
51
+ lt(other) {
52
+ return new Expr(this.inner.lt(coerce(other).inner));
53
+ }
54
+ /** Compare for less than or equal to. */
55
+ lte(other) {
56
+ return new Expr(this.inner.lte(coerce(other).inner));
57
+ }
58
+ /** Compare for greater than. */
59
+ gt(other) {
60
+ return new Expr(this.inner.gt(coerce(other).inner));
61
+ }
62
+ /** Compare for greater than or equal to. */
63
+ gte(other) {
64
+ return new Expr(this.inner.gte(coerce(other).inner));
65
+ }
66
+ /** Combine two predicates with AND. */
67
+ and(other) {
68
+ return new Expr(this.inner.and(other.inner));
69
+ }
70
+ /** Combine two predicates with OR. */
71
+ or(other) {
72
+ return new Expr(this.inner.or(other.inner));
73
+ }
74
+ /** Negate this predicate. */
75
+ not() {
76
+ return new Expr(this.inner.not());
77
+ }
78
+ /** Add a value. */
79
+ add(other) {
80
+ return new Expr(this.inner.add(coerce(other).inner));
81
+ }
82
+ /** Subtract a value. */
83
+ sub(other) {
84
+ return new Expr(this.inner.sub(coerce(other).inner));
85
+ }
86
+ /** Multiply by a value. */
87
+ mul(other) {
88
+ return new Expr(this.inner.mul(coerce(other).inner));
89
+ }
90
+ /** Divide by a value. */
91
+ div(other) {
92
+ return new Expr(this.inner.div(coerce(other).inner));
93
+ }
94
+ /** Convert a string to lowercase. */
95
+ lower() {
96
+ return new Expr(this.inner.lower());
97
+ }
98
+ /** Convert a string to uppercase. */
99
+ upper() {
100
+ return new Expr(this.inner.upper());
101
+ }
102
+ /** Test whether a string contains a substring. */
103
+ contains(substr) {
104
+ return new Expr(this.inner.contains(coerce(substr).inner));
105
+ }
106
+ /** Test membership in a list of values. */
107
+ isIn(values) {
108
+ return new Expr(this.inner.isIn(values.map((v) => coerce(v).inner)));
109
+ }
110
+ /** Cast to an Arrow data type, such as "Int64". */
111
+ cast(dataType) {
112
+ return new Expr(this.inner.cast(dataType));
113
+ }
114
+ /** Serialize with the LanceDB SQL dialect, preserving column case. */
115
+ toSql() {
116
+ return this.inner.toSql();
117
+ }
118
+ }
119
+ exports.Expr = Expr;
120
+ /** Reference a column by its exact, case-sensitive name. */
121
+ function col(name) {
122
+ return new Expr((0, native_js_1.col)(name));
123
+ }
124
+ /** Create a string or numeric literal. Unsafe integers are represented as Float64. */
125
+ function lit(value) {
126
+ if (typeof value === "string") {
127
+ return new Expr((0, native_js_1.lit)(value));
128
+ }
129
+ if (Number.isSafeInteger(value)) {
130
+ return new Expr((0, native_js_1.litInt)(value));
131
+ }
132
+ return new Expr((0, native_js_1.lit)(value));
133
+ }
134
+ /** Create a boolean literal. */
135
+ function litBool(value) {
136
+ return new Expr((0, native_js_1.litBool)(value));
137
+ }
138
+ /** Create an Int64 literal from a JavaScript safe integer. Other numbers throw RangeError. */
139
+ function litInt(value) {
140
+ if (!Number.isSafeInteger(value)) {
141
+ throw new RangeError("Integer literals must be safe integers");
142
+ }
143
+ return new Expr((0, native_js_1.litInt)(value));
144
+ }
145
+ /** Call a registered SQL function, such as `func("lower", col("firstName"))`. */
146
+ function func(name, ...args) {
147
+ return new Expr((0, native_js_1.func)(name, args.map((a) => coerce(a).inner)));
148
+ }
package/dist/header.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Header providers for LanceDB remote connections.
2
+ * Header providers for LanceDB Enterprise connections.
3
3
  *
4
4
  * This module provides a flexible header management framework for LanceDB remote
5
5
  * connections, allowing users to implement custom header strategies for
package/dist/header.js CHANGED
@@ -4,7 +4,7 @@
4
4
  Object.defineProperty(exports, "__esModule", { value: true });
5
5
  exports.OAuthHeaderProvider = exports.StaticHeaderProvider = exports.HeaderProvider = void 0;
6
6
  /**
7
- * Header providers for LanceDB remote connections.
7
+ * Header providers for LanceDB Enterprise connections.
8
8
  *
9
9
  * This module provides a flexible header management framework for LanceDB remote
10
10
  * connections, allowing users to implement custom header strategies for
package/dist/index.d.ts CHANGED
@@ -11,12 +11,12 @@ export { AddColumnsSql, ConnectionOptions, ConnectNamespaceOptions, IndexStatist
11
11
  export { makeArrowTable, makeJsonField, MakeArrowTableOptions, Data, VectorColumnOptions, } from "./arrow";
12
12
  export { blob, isBlobField, BlobFile } from "./blob";
13
13
  export type { BlobData, BlobInput, BlobOptions, BlobRange, BlobReadOptions, BlobUri, } from "./blob";
14
- export { Connection, CreateTableOptions, TableNamesOptions, ListTablesOptions, OpenTableOptions, ListNamespacesOptions, CreateNamespaceOptions, DropNamespaceOptions, ListNamespacesResponse, ListTablesResponse, CreateNamespaceResponse, DropNamespaceResponse, DescribeNamespaceResponse, RenameTableOptions, } from "./connection";
14
+ export { Connection, CreateTableOptions, TableNamesOptions, OpenTableOptions, CreateNamespaceOptions, DropNamespaceOptions, CreateNamespaceResponse, DropNamespaceResponse, DescribeNamespaceResponse, RenameTableOptions, } from "./connection";
15
15
  export { JobFailureInfo, JobInfo, Session } from "./native.js";
16
16
  export { Job, JobEventsOptions } from "./job";
17
17
  export { AutoQuery, ExecutableQuery, Query, QueryBase, VectorQuery, TakeQuery, AnalyzePlanDistributedMetrics, BlobMode, QueryExecutionOptions, ColumnOrdering, FullTextSearchOptions, RecordBatchIterator, FullTextQuery, MatchQuery, PhraseQuery, BoostQuery, MultiMatchQuery, BooleanQuery, FullTextQueryType, Operator, Occur, } from "./query";
18
18
  export { Index, IndexOptions, IvfPqOptions, IvfRqOptions, IvfFlatOptions, HnswPqOptions, HnswSqOptions, FtsOptions, BaseTokenizer, } from "./indices";
19
- export { Table, Branches, BranchColumnSummary, BranchColumnChange, BranchIndexSummary, BranchRowCountSummary, CherryPickError, BranchDiff, CherryPickPreview, CherryPickResult, AddDataOptions, UpdateOptions, OptimizeOptions, Version, WriteProgress, FtsToken, TokenizeTableOptions, MemWalWriteSpec, MemWalStats, TableShardStats, SsTableStats, MemtableStats, ColumnAlteration, FieldMetadataUpdate, } from "./table";
19
+ export { Table, Branches, BranchColumnSummary, BranchColumnChange, BranchIndexSummary, BranchRowCountSummary, CherryPickError, BranchDiff, CherryPickPreview, CherryPickResult, AddDataOptions, UpdateOptions, OptimizeOptions, Version, WriteProgress, FtsToken, TokenizeTableOptions, RTEWriteSpec, RTEStats, TableShardStats, SsTableStats, MemtableStats, ColumnAlteration, FieldMetadataUpdate, } from "./table";
20
20
  export { HeaderProvider, StaticHeaderProvider, OAuthHeaderProvider, TokenResponse, } from "./header";
21
21
  export { ClientAuthMethod, OAuthConfig, OAuthFlowType, OAuthSession, SessionLogout, SessionStatus, TokenCacheOptions, } from "./oauth";
22
22
  export { MergeInsertBuilder, WriteExecutionOptions } from "./merge";
@@ -26,6 +26,8 @@ export { Scannable, ScannableOptions } from "./scannable";
26
26
  export * as rerankers from "./rerankers";
27
27
  export { SchemaLike, TableLike, DataTypeLike, FieldLike, RecordBatchLike, DataLike, IntoVector, MultiVector, } from "./arrow";
28
28
  export { IntoSql, packBits } from "./util";
29
+ export { Expr, col, lit, litBool, litInt, func } from "./expr";
30
+ export type { ExprLike } from "./expr";
29
31
  /**
30
32
  * Options for tokenizing a full-text search query without a table index.
31
33
  */
@@ -74,11 +76,11 @@ export declare function tokenize(query: string, options?: Partial<TokenizeOption
74
76
  *
75
77
  * Accepted formats:
76
78
  *
77
- * - `/path/to/database` - local database
79
+ * - `/path/to/database` - database on the local file system
78
80
  * - `s3://bucket/path/to/database` or `gs://bucket/path/to/database` - database on cloud storage
79
- * - `db://host:port` - remote database (LanceDB cloud)
81
+ * - `db://host:port` - LanceDB Enterprise or LanceDB Cloud (legacy) database
80
82
  * @param {string} uri - The uri of the database. If the database uri starts
81
- * with `db://` then it connects to a remote database.
83
+ * with `db://` then it connects to LanceDB Enterprise or LanceDB Cloud (legacy).
82
84
  * @see {@link ConnectionOptions} for more details on the URI format.
83
85
  * @param options - The options to use when connecting to the database
84
86
  * @example
@@ -111,9 +113,9 @@ export declare function connect(uri: string, options?: Partial<ConnectionOptions
111
113
  *
112
114
  * Accepted formats:
113
115
  *
114
- * - `/path/to/database` - local database
116
+ * - `/path/to/database` - database on the local file system
115
117
  * - `s3://bucket/path/to/database` or `gs://bucket/path/to/database` - database on cloud storage
116
- * - `db://host:port` - remote database (LanceDB cloud)
118
+ * - `db://host:port` - LanceDB Enterprise or LanceDB Cloud (legacy) database
117
119
  * @param options - The options to use when connecting to the database
118
120
  * @see {@link ConnectionOptions} for more details on the URI format.
119
121
  * @example
@@ -186,7 +188,7 @@ export interface RestNamespaceConfig {
186
188
  * Connect to a LanceDB database through a namespace.
187
189
  *
188
190
  * Unlike {@link connect}, which routes by URI scheme (local path vs.
189
- * `db://` cloud), `connectNamespace` always returns a namespace-backed
191
+ * `db://`), `connectNamespace` always returns a namespace-backed
190
192
  * connection. The `implName` selects the namespace implementation:
191
193
  *
192
194
  * - `"dir"` — directory namespace, configured with {@link DirNamespaceConfig}.
package/dist/index.js CHANGED
@@ -2,7 +2,8 @@
2
2
  // SPDX-License-Identifier: Apache-2.0
3
3
  // SPDX-FileCopyrightText: Copyright The LanceDB Authors
4
4
  Object.defineProperty(exports, "__esModule", { value: true });
5
- exports.Listing = exports.connectCatalog = exports.DatabaseNames = exports.Catalog = exports.packBits = exports.rerankers = exports.Scannable = exports.PermutationBuilder = exports.permutationBuilder = exports.embedding = exports.MergeInsertBuilder = exports.OAuthSession = exports.OAuthFlowType = exports.ClientAuthMethod = exports.OAuthHeaderProvider = exports.StaticHeaderProvider = exports.HeaderProvider = exports.Branches = exports.Table = exports.Index = exports.Occur = exports.Operator = exports.FullTextQueryType = exports.BooleanQuery = exports.MultiMatchQuery = exports.BoostQuery = exports.PhraseQuery = exports.MatchQuery = exports.RecordBatchIterator = exports.TakeQuery = exports.VectorQuery = exports.QueryBase = exports.Query = exports.AutoQuery = exports.Job = exports.Session = exports.Connection = exports.BlobFile = exports.isBlobField = exports.blob = exports.VectorColumnOptions = exports.MakeArrowTableOptions = exports.makeJsonField = exports.makeArrowTable = exports.BranchContents = exports.TagContents = exports.Tags = exports.instrumentLanceDbMetrics = exports.NativeJsHeaderProvider = exports.MaterializedView = void 0;
5
+ exports.litBool = exports.lit = exports.col = exports.Expr = exports.packBits = exports.rerankers = exports.Scannable = exports.PermutationBuilder = exports.permutationBuilder = exports.embedding = exports.MergeInsertBuilder = exports.OAuthSession = exports.OAuthFlowType = exports.ClientAuthMethod = exports.OAuthHeaderProvider = exports.StaticHeaderProvider = exports.HeaderProvider = exports.Branches = exports.Table = exports.Index = exports.Occur = exports.Operator = exports.FullTextQueryType = exports.BooleanQuery = exports.MultiMatchQuery = exports.BoostQuery = exports.PhraseQuery = exports.MatchQuery = exports.RecordBatchIterator = exports.TakeQuery = exports.VectorQuery = exports.QueryBase = exports.Query = exports.AutoQuery = exports.Job = exports.Session = exports.Connection = exports.BlobFile = exports.isBlobField = exports.blob = exports.VectorColumnOptions = exports.MakeArrowTableOptions = exports.makeJsonField = exports.makeArrowTable = exports.BranchContents = exports.TagContents = exports.Tags = exports.instrumentLanceDbMetrics = exports.NativeJsHeaderProvider = exports.MaterializedView = void 0;
6
+ exports.Listing = exports.connectCatalog = exports.DatabaseNames = exports.Catalog = exports.func = exports.litInt = void 0;
6
7
  exports.tokenize = tokenize;
7
8
  exports.connect = connect;
8
9
  exports.connectNamespace = connectNamespace;
@@ -76,6 +77,13 @@ Object.defineProperty(exports, "Scannable", { enumerable: true, get: function ()
76
77
  exports.rerankers = require("./rerankers");
77
78
  var util_1 = require("./util");
78
79
  Object.defineProperty(exports, "packBits", { enumerable: true, get: function () { return util_1.packBits; } });
80
+ var expr_1 = require("./expr");
81
+ Object.defineProperty(exports, "Expr", { enumerable: true, get: function () { return expr_1.Expr; } });
82
+ Object.defineProperty(exports, "col", { enumerable: true, get: function () { return expr_1.col; } });
83
+ Object.defineProperty(exports, "lit", { enumerable: true, get: function () { return expr_1.lit; } });
84
+ Object.defineProperty(exports, "litBool", { enumerable: true, get: function () { return expr_1.litBool; } });
85
+ Object.defineProperty(exports, "litInt", { enumerable: true, get: function () { return expr_1.litInt; } });
86
+ Object.defineProperty(exports, "func", { enumerable: true, get: function () { return expr_1.func; } });
79
87
  /**
80
88
  * Tokenize a full-text search query using an explicit tokenizer.
81
89
  *
@@ -122,8 +130,10 @@ async function connect(uriOrOptions, optionsOrSession, sessionOrHeaderProvider,
122
130
  if (!uri) {
123
131
  throw new Error("uri is required");
124
132
  }
125
- finalOptions = finalOptions ?? {};
126
- finalOptions.storageOptions = (0, connection_1.cleanseStorageOptions)(finalOptions.storageOptions);
133
+ finalOptions = {
134
+ ...finalOptions,
135
+ storageOptions: (0, connection_1.cleanseStorageOptions)(finalOptions.storageOptions),
136
+ };
127
137
  // Create native header provider if one was provided
128
138
  let nativeProvider;
129
139
  if (finalHeaderProvider) {
@@ -176,9 +186,10 @@ async function connectNamespace(implName, configOrProperties, options) {
176
186
  else {
177
187
  properties = configOrProperties;
178
188
  }
179
- const finalOptions = (options ??
180
- {});
181
- finalOptions.storageOptions = (0, connection_1.cleanseStorageOptions)(finalOptions.storageOptions);
189
+ const finalOptions = {
190
+ ...options,
191
+ storageOptions: (0, connection_1.cleanseStorageOptions)(options?.storageOptions),
192
+ };
182
193
  const nativeConn = await native_js_1.Connection.newWithNamespace(implName, properties, finalOptions);
183
194
  return new connection_1.LocalConnection(nativeConn);
184
195
  }
package/dist/indices.d.ts CHANGED
@@ -6,14 +6,29 @@ export interface IvfPqOptions {
6
6
  * The number of IVF partitions to create.
7
7
  *
8
8
  * This value should generally scale with the number of rows in the dataset.
9
- * By default the number of partitions is the square root of the number of
10
- * rows.
9
+ * When set, this takes precedence over `targetPartitionSize`. When omitted,
10
+ * the partition count is derived from `targetPartitionSize`, which defaults
11
+ * to 8192 rows for this index type.
11
12
  *
12
13
  * If this value is too large then the first part of the search (picking the
13
14
  * right partition) will be slow. If this value is too small then the second
14
15
  * part of the search (searching within a partition) will be slow.
15
16
  */
16
17
  numPartitions?: number;
18
+ /**
19
+ * The target number of rows in each IVF partition.
20
+ *
21
+ * This is an alternative to `numPartitions`. When it is set and
22
+ * `numPartitions` is not, the number of partitions is derived by dividing
23
+ * the number of rows by this value. When both are set, `numPartitions` is
24
+ * used and this value is ignored. When neither is set, the target is
25
+ * 8192 rows.
26
+ *
27
+ * Larger partitions mean fewer of them, which makes the first part of the
28
+ * search (picking the right partitions) faster and the second part
29
+ * (searching within a partition) slower.
30
+ */
31
+ targetPartitionSize?: number;
17
32
  /**
18
33
  * Number of sub-vectors of PQ.
19
34
  *
@@ -106,20 +121,36 @@ export interface IvfRqOptions {
106
121
  * The number of IVF partitions to create.
107
122
  *
108
123
  * This value should generally scale with the number of rows in the dataset.
109
- * By default the number of partitions is the square root of the number of
110
- * rows.
124
+ * When set, this takes precedence over `targetPartitionSize`. When omitted,
125
+ * the partition count is derived from `targetPartitionSize`, which defaults
126
+ * to 4096 rows for this index type.
111
127
  *
112
128
  * If this value is too large then the first part of the search (picking the
113
129
  * right partition) will be slow. If this value is too small then the second
114
130
  * part of the search (searching within a partition) will be slow.
115
131
  */
116
132
  numPartitions?: number;
133
+ /**
134
+ * The target number of rows in each IVF partition.
135
+ *
136
+ * This is an alternative to `numPartitions`. When it is set and
137
+ * `numPartitions` is not, the number of partitions is derived by dividing
138
+ * the number of rows by this value. When both are set, `numPartitions` is
139
+ * used and this value is ignored. When neither is set, the target is
140
+ * 4096 rows.
141
+ *
142
+ * Larger partitions mean fewer of them, which makes the first part of the
143
+ * search (picking the right partitions) faster and the second part
144
+ * (searching within a partition) slower.
145
+ */
146
+ targetPartitionSize?: number;
117
147
  /**
118
148
  * Number of bits per dimension for residual quantization.
119
149
  *
120
150
  * This value controls how much each residual component is compressed. The more
121
151
  * bits, the more accurate the index will be but the slower search. Typical values
122
- * are small integers; the default is 1 bit per dimension.
152
+ * are small integers. If unset, uses Lance's default (currently 5 bits per
153
+ * dimension). Set to 1 for maximum compression.
123
154
  */
124
155
  numBits?: number;
125
156
  /**
@@ -197,6 +228,8 @@ export interface HnswPqOptions {
197
228
  /**
198
229
  * The number of IVF partitions to create.
199
230
  *
231
+ * When set, this takes precedence over `targetPartitionSize`.
232
+ *
200
233
  * For HNSW, we recommend a small number of partitions. Setting this to 1 works
201
234
  * well for most tables. For very large tables, training just one HNSW graph
202
235
  * will require too much memory. Each partition becomes its own HNSW graph, so
@@ -204,6 +237,20 @@ export interface HnswPqOptions {
204
237
  *
205
238
  */
206
239
  numPartitions?: number;
240
+ /**
241
+ * The target number of rows in each IVF partition.
242
+ *
243
+ * This is an alternative to `numPartitions`. When it is set and
244
+ * `numPartitions` is not, the number of partitions is derived by dividing
245
+ * the number of rows by this value. When both are set, `numPartitions` is
246
+ * used and this value is ignored. When neither is set, the target is
247
+ * 1,048,576 rows.
248
+ *
249
+ * Larger partitions mean fewer of them, which makes the first part of the
250
+ * search (picking the right partitions) faster and the second part
251
+ * (searching within a partition) slower.
252
+ */
253
+ targetPartitionSize?: number;
207
254
  /**
208
255
  * Number of sub-vectors of PQ.
209
256
  *
@@ -306,6 +353,8 @@ export interface HnswSqOptions {
306
353
  /**
307
354
  * The number of IVF partitions to create.
308
355
  *
356
+ * When set, this takes precedence over `targetPartitionSize`.
357
+ *
309
358
  * For HNSW, we recommend a small number of partitions. Setting this to 1 works
310
359
  * well for most tables. For very large tables, training just one HNSW graph
311
360
  * will require too much memory. Each partition becomes its own HNSW graph, so
@@ -313,6 +362,20 @@ export interface HnswSqOptions {
313
362
  *
314
363
  */
315
364
  numPartitions?: number;
365
+ /**
366
+ * The target number of rows in each IVF partition.
367
+ *
368
+ * This is an alternative to `numPartitions`. When it is set and
369
+ * `numPartitions` is not, the number of partitions is derived by dividing
370
+ * the number of rows by this value. When both are set, `numPartitions` is
371
+ * used and this value is ignored. When neither is set, the target is
372
+ * 1,048,576 rows.
373
+ *
374
+ * Larger partitions mean fewer of them, which makes the first part of the
375
+ * search (picking the right partitions) faster and the second part
376
+ * (searching within a partition) slower.
377
+ */
378
+ targetPartitionSize?: number;
316
379
  /**
317
380
  * Max iterations to train kmeans.
318
381
  *
@@ -377,14 +440,29 @@ export interface IvfFlatOptions {
377
440
  * The number of IVF partitions to create.
378
441
  *
379
442
  * This value should generally scale with the number of rows in the dataset.
380
- * By default the number of partitions is the square root of the number of
381
- * rows.
443
+ * When set, this takes precedence over `targetPartitionSize`. When omitted,
444
+ * the partition count is derived from `targetPartitionSize`, which defaults
445
+ * to 4096 rows for this index type.
382
446
  *
383
447
  * If this value is too large then the first part of the search (picking the
384
448
  * right partition) will be slow. If this value is too small then the second
385
449
  * part of the search (searching within a partition) will be slow.
386
450
  */
387
451
  numPartitions?: number;
452
+ /**
453
+ * The target number of rows in each IVF partition.
454
+ *
455
+ * This is an alternative to `numPartitions`. When it is set and
456
+ * `numPartitions` is not, the number of partitions is derived by dividing
457
+ * the number of rows by this value. When both are set, `numPartitions` is
458
+ * used and this value is ignored. When neither is set, the target is
459
+ * 4096 rows.
460
+ *
461
+ * Larger partitions mean fewer of them, which makes the first part of the
462
+ * search (picking the right partitions) faster and the second part
463
+ * (searching within a partition) slower.
464
+ */
465
+ targetPartitionSize?: number;
388
466
  /**
389
467
  * Distance type to use to build the index.
390
468
  *
@@ -632,7 +710,7 @@ export declare class Index {
632
710
  * Create a label list index.
633
711
  *
634
712
  * LabelList index is a scalar index that can be used on `List<T>` columns to
635
- * support queries with `array_contains_all` and `array_contains_any`
713
+ * support queries with `array_has_all` and `array_has_any`
636
714
  * using an underlying bitmap index.
637
715
  */
638
716
  static labelList(): Index;
package/dist/indices.js CHANGED
@@ -32,7 +32,7 @@ class Index {
32
32
  * currently is also a memory intensive operation.
33
33
  */
34
34
  static ivfPq(options) {
35
- return new Index(native_1.Index.ivfPq(options?.distanceType, options?.numPartitions, options?.numSubVectors, options?.numBits, options?.maxIterations, options?.sampleRate));
35
+ return new Index(native_1.Index.ivfPq(options?.distanceType, options?.numPartitions, options?.numSubVectors, options?.numBits, options?.maxIterations, options?.sampleRate, options?.targetPartitionSize));
36
36
  }
37
37
  /**
38
38
  * Create an IvfRq index
@@ -51,7 +51,7 @@ class Index {
51
51
  * currently is also a memory intensive operation.
52
52
  */
53
53
  static ivfRq(options) {
54
- return new Index(native_1.Index.ivfRq(options?.distanceType, options?.numPartitions, options?.numBits, options?.maxIterations, options?.sampleRate));
54
+ return new Index(native_1.Index.ivfRq(options?.distanceType, options?.numPartitions, options?.numBits, options?.maxIterations, options?.sampleRate, options?.targetPartitionSize));
55
55
  }
56
56
  /**
57
57
  * Create an IvfFlat index
@@ -70,7 +70,7 @@ class Index {
70
70
  * currently is also a memory intensive operation.
71
71
  */
72
72
  static ivfFlat(options) {
73
- return new Index(native_1.Index.ivfFlat(options?.distanceType, options?.numPartitions, options?.maxIterations, options?.sampleRate));
73
+ return new Index(native_1.Index.ivfFlat(options?.distanceType, options?.numPartitions, options?.maxIterations, options?.sampleRate, options?.targetPartitionSize));
74
74
  }
75
75
  /**
76
76
  * Create a btree index
@@ -109,7 +109,7 @@ class Index {
109
109
  * Create a label list index.
110
110
  *
111
111
  * LabelList index is a scalar index that can be used on `List<T>` columns to
112
- * support queries with `array_contains_all` and `array_contains_any`
112
+ * support queries with `array_has_all` and `array_has_any`
113
113
  * using an underlying bitmap index.
114
114
  */
115
115
  static labelList() {
@@ -148,7 +148,7 @@ class Index {
148
148
  *
149
149
  */
150
150
  static hnswPq(options) {
151
- return new Index(native_1.Index.hnswPq(options?.distanceType, options?.numPartitions, options?.numSubVectors, options?.maxIterations, options?.sampleRate, options?.m, options?.efConstruction));
151
+ return new Index(native_1.Index.hnswPq(options?.distanceType, options?.numPartitions, options?.numSubVectors, options?.maxIterations, options?.sampleRate, options?.m, options?.efConstruction, options?.targetPartitionSize));
152
152
  }
153
153
  /**
154
154
  *
@@ -160,7 +160,7 @@ class Index {
160
160
  *
161
161
  */
162
162
  static hnswSq(options) {
163
- return new Index(native_1.Index.hnswSq(options?.distanceType, options?.numPartitions, options?.maxIterations, options?.sampleRate, options?.m, options?.efConstruction));
163
+ return new Index(native_1.Index.hnswSq(options?.distanceType, options?.numPartitions, options?.maxIterations, options?.sampleRate, options?.m, options?.efConstruction, options?.targetPartitionSize));
164
164
  }
165
165
  }
166
166
  exports.Index = Index;
package/dist/job.d.ts CHANGED
@@ -19,7 +19,8 @@ export interface JobEventsOptions {
19
19
  * - {@link Job.refresh} and {@link Job.status} fetch the whole record.
20
20
  * - {@link Job.wait} records the terminal state it establishes, but not the
21
21
  * rest of the record.
22
- * - Everything is null until one of those runs.
22
+ * - Registry details are null until one of those runs. Query handles report
23
+ * jobType "query" immediately.
23
24
  *
24
25
  * @hideconstructor
25
26
  */
@@ -29,15 +30,17 @@ export declare class Job {
29
30
  /**
30
31
  * Identifies the operation on the server that is running it.
31
32
  *
32
- * Operations that run in this process have no server id. The value is
33
- * opaque: parsing it or storing it to resume the job later is not supported.
33
+ * Registry handles expose a registry job ID; query handles expose a
34
+ * connection-scoped SQL query UUID string. Local handles have no ID.
35
+ * Query handles report jobType "query". Their IDs are not registry IDs or
36
+ * durable resume tokens.
34
37
  */
35
38
  get id(): string | null;
36
39
  /** The last observed lifecycle state, without contacting the backend. */
37
40
  get state(): string | null;
38
41
  /**
39
- * The job's type, as the server names it. Null for an in-process job, which
40
- * has no server-side record.
42
+ * "query" immediately for SQL-backed handles; otherwise the cached
43
+ * server-reported job type. Null for in-process handles.
41
44
  */
42
45
  get jobType(): string | null;
43
46
  /** When the job was created, in milliseconds since the epoch. */
package/dist/job.js CHANGED
@@ -16,7 +16,8 @@ const apache_arrow_1 = require("apache-arrow");
16
16
  * - {@link Job.refresh} and {@link Job.status} fetch the whole record.
17
17
  * - {@link Job.wait} records the terminal state it establishes, but not the
18
18
  * rest of the record.
19
- * - Everything is null until one of those runs.
19
+ * - Registry details are null until one of those runs. Query handles report
20
+ * jobType "query" immediately.
20
21
  *
21
22
  * @hideconstructor
22
23
  */
@@ -28,8 +29,10 @@ class Job {
28
29
  /**
29
30
  * Identifies the operation on the server that is running it.
30
31
  *
31
- * Operations that run in this process have no server id. The value is
32
- * opaque: parsing it or storing it to resume the job later is not supported.
32
+ * Registry handles expose a registry job ID; query handles expose a
33
+ * connection-scoped SQL query UUID string. Local handles have no ID.
34
+ * Query handles report jobType "query". Their IDs are not registry IDs or
35
+ * durable resume tokens.
33
36
  */
34
37
  get id() {
35
38
  return this.inner.id ?? null;
@@ -39,8 +42,8 @@ class Job {
39
42
  return this.inner.state ?? null;
40
43
  }
41
44
  /**
42
- * The job's type, as the server names it. Null for an in-process job, which
43
- * has no server-side record.
45
+ * "query" immediately for SQL-backed handles; otherwise the cached
46
+ * server-reported job type. Null for in-process handles.
44
47
  */
45
48
  get jobType() {
46
49
  return this.inner.jobType ?? null;
@@ -56,12 +56,16 @@ export declare class MaterializedView {
56
56
  definition(): Promise<MaterializedViewDefinition>;
57
57
  /**
58
58
  * Recompute the view from its source.
59
+ * Local refresh requires a source build with `experimental-functions`.
59
60
  *
60
- * Every refresh rebuilds the complete view. For local views,
61
- * `sourceVersion` refreshes to that source version instead of the latest;
62
- * remote SQL refreshes do not support source-version pinning.
61
+ * `full: true` forces a remote rebuild; otherwise the server chooses the
62
+ * refresh mode. Local views always rebuild, and `sourceVersion` selects a
63
+ * source version instead of the latest. Remote SQL refreshes do not support
64
+ * source-version pinning. Their results leave `mode`, `rowsWritten`, and
65
+ * `sourceVersion` absent because the SQL job adapter does not expose these metrics.
63
66
  */
64
67
  refresh(options?: {
68
+ full?: boolean;
65
69
  sourceVersion?: number;
66
70
  }): Promise<RefreshMaterializedViewResult>;
67
71
  }