@lancedb/lancedb 0.5.2 → 0.7.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 (89) hide show
  1. package/Cargo.toml +3 -3
  2. package/biome.json +19 -3
  3. package/dist/arrow.d.ts +41 -8
  4. package/dist/arrow.js +4 -4
  5. package/dist/connection.d.ts +49 -29
  6. package/dist/connection.js +21 -73
  7. package/dist/embedding/embedding_function.d.ts +9 -1
  8. package/dist/embedding/embedding_function.js +6 -0
  9. package/dist/embedding/openai.d.ts +6 -5
  10. package/dist/embedding/openai.js +4 -2
  11. package/dist/embedding/registry.d.ts +6 -11
  12. package/dist/index.d.ts +51 -3
  13. package/dist/index.js +28 -4
  14. package/dist/merge.d.ts +54 -0
  15. package/dist/merge.js +64 -0
  16. package/dist/native.d.ts +29 -3
  17. package/dist/native.js +26 -9
  18. package/dist/query.d.ts +33 -10
  19. package/dist/query.js +100 -13
  20. package/dist/remote/client.d.ts +28 -0
  21. package/dist/remote/client.js +172 -0
  22. package/dist/remote/connection.d.ts +25 -0
  23. package/dist/remote/connection.js +110 -0
  24. package/dist/remote/index.d.ts +3 -0
  25. package/dist/remote/index.js +9 -0
  26. package/dist/remote/table.d.ts +42 -0
  27. package/dist/remote/table.js +179 -0
  28. package/dist/sanitize.d.ts +3 -2
  29. package/dist/sanitize.js +55 -1
  30. package/dist/table.d.ts +105 -30
  31. package/dist/table.js +94 -237
  32. package/dist/util.d.ts +14 -0
  33. package/dist/util.js +65 -0
  34. package/examples/ann_indexes.ts +49 -0
  35. package/examples/basic.ts +149 -0
  36. package/examples/embedding.ts +83 -0
  37. package/examples/filtering.ts +34 -0
  38. package/examples/jsconfig.json +27 -0
  39. package/examples/package-lock.json +79 -0
  40. package/examples/package.json +18 -0
  41. package/examples/search.ts +37 -0
  42. package/lancedb/arrow.ts +80 -23
  43. package/lancedb/connection.ts +107 -92
  44. package/lancedb/embedding/embedding_function.ts +12 -1
  45. package/lancedb/embedding/openai.ts +11 -6
  46. package/lancedb/embedding/registry.ts +34 -22
  47. package/lancedb/index.ts +101 -2
  48. package/lancedb/merge.ts +70 -0
  49. package/lancedb/query.ts +114 -28
  50. package/lancedb/remote/client.ts +221 -0
  51. package/lancedb/remote/connection.ts +201 -0
  52. package/lancedb/remote/index.ts +3 -0
  53. package/lancedb/remote/table.ts +226 -0
  54. package/lancedb/sanitize.ts +73 -1
  55. package/lancedb/table.ts +320 -132
  56. package/lancedb/util.ts +69 -0
  57. package/native.d.ts +208 -0
  58. package/nodejs-artifacts/arrow.d.ts +41 -8
  59. package/nodejs-artifacts/arrow.js +4 -4
  60. package/nodejs-artifacts/connection.d.ts +49 -29
  61. package/nodejs-artifacts/connection.js +21 -73
  62. package/nodejs-artifacts/embedding/embedding_function.d.ts +9 -1
  63. package/nodejs-artifacts/embedding/embedding_function.js +6 -0
  64. package/nodejs-artifacts/embedding/openai.d.ts +6 -5
  65. package/nodejs-artifacts/embedding/openai.js +4 -2
  66. package/nodejs-artifacts/embedding/registry.d.ts +6 -11
  67. package/nodejs-artifacts/index.d.ts +51 -3
  68. package/nodejs-artifacts/index.js +28 -4
  69. package/nodejs-artifacts/merge.d.ts +54 -0
  70. package/nodejs-artifacts/merge.js +64 -0
  71. package/nodejs-artifacts/native.d.ts +29 -3
  72. package/nodejs-artifacts/native.js +26 -9
  73. package/nodejs-artifacts/query.d.ts +33 -10
  74. package/nodejs-artifacts/query.js +100 -13
  75. package/nodejs-artifacts/remote/client.d.ts +28 -0
  76. package/nodejs-artifacts/remote/client.js +172 -0
  77. package/nodejs-artifacts/remote/connection.d.ts +25 -0
  78. package/nodejs-artifacts/remote/connection.js +110 -0
  79. package/nodejs-artifacts/remote/index.d.ts +3 -0
  80. package/nodejs-artifacts/remote/index.js +9 -0
  81. package/nodejs-artifacts/remote/table.d.ts +42 -0
  82. package/nodejs-artifacts/remote/table.js +179 -0
  83. package/nodejs-artifacts/sanitize.d.ts +3 -2
  84. package/nodejs-artifacts/sanitize.js +55 -1
  85. package/nodejs-artifacts/table.d.ts +105 -30
  86. package/nodejs-artifacts/table.js +94 -237
  87. package/nodejs-artifacts/util.d.ts +14 -0
  88. package/nodejs-artifacts/util.js +65 -0
  89. package/package.json +25 -11
package/dist/index.js CHANGED
@@ -13,14 +13,16 @@
13
13
  // See the License for the specific language governing permissions and
14
14
  // limitations under the License.
15
15
  Object.defineProperty(exports, "__esModule", { value: true });
16
- exports.embedding = exports.Table = exports.Index = exports.RecordBatchIterator = exports.VectorQuery = exports.QueryBase = exports.Query = exports.Connection = exports.connect = exports.VectorColumnOptions = exports.MakeArrowTableOptions = exports.makeArrowTable = void 0;
16
+ exports.connect = exports.embedding = exports.Table = exports.Index = exports.RecordBatchIterator = exports.VectorQuery = exports.QueryBase = exports.Query = exports.Connection = exports.VectorColumnOptions = exports.MakeArrowTableOptions = exports.makeArrowTable = void 0;
17
+ const connection_1 = require("./connection");
18
+ const native_js_1 = require("./native.js");
19
+ const remote_1 = require("./remote");
17
20
  var arrow_1 = require("./arrow");
18
21
  Object.defineProperty(exports, "makeArrowTable", { enumerable: true, get: function () { return arrow_1.makeArrowTable; } });
19
22
  Object.defineProperty(exports, "MakeArrowTableOptions", { enumerable: true, get: function () { return arrow_1.MakeArrowTableOptions; } });
20
23
  Object.defineProperty(exports, "VectorColumnOptions", { enumerable: true, get: function () { return arrow_1.VectorColumnOptions; } });
21
- var connection_1 = require("./connection");
22
- Object.defineProperty(exports, "connect", { enumerable: true, get: function () { return connection_1.connect; } });
23
- Object.defineProperty(exports, "Connection", { enumerable: true, get: function () { return connection_1.Connection; } });
24
+ var connection_2 = require("./connection");
25
+ Object.defineProperty(exports, "Connection", { enumerable: true, get: function () { return connection_2.Connection; } });
24
26
  var query_1 = require("./query");
25
27
  Object.defineProperty(exports, "Query", { enumerable: true, get: function () { return query_1.Query; } });
26
28
  Object.defineProperty(exports, "QueryBase", { enumerable: true, get: function () { return query_1.QueryBase; } });
@@ -31,3 +33,25 @@ Object.defineProperty(exports, "Index", { enumerable: true, get: function () { r
31
33
  var table_1 = require("./table");
32
34
  Object.defineProperty(exports, "Table", { enumerable: true, get: function () { return table_1.Table; } });
33
35
  exports.embedding = require("./embedding");
36
+ async function connect(uriOrOptions, opts = {}) {
37
+ let uri;
38
+ if (typeof uriOrOptions !== "string") {
39
+ const { uri: uri_, ...options } = uriOrOptions;
40
+ uri = uri_;
41
+ opts = options;
42
+ }
43
+ else {
44
+ uri = uriOrOptions;
45
+ }
46
+ if (!uri) {
47
+ throw new Error("uri is required");
48
+ }
49
+ if (uri?.startsWith("db://")) {
50
+ return new remote_1.RemoteConnection(uri, opts);
51
+ }
52
+ opts = opts ?? {};
53
+ opts.storageOptions = (0, connection_1.cleanseStorageOptions)(opts.storageOptions);
54
+ const nativeConn = await native_js_1.Connection.new(uri, opts);
55
+ return new connection_1.LocalConnection(nativeConn);
56
+ }
57
+ exports.connect = connect;
@@ -0,0 +1,54 @@
1
+ import { Data } from "./arrow";
2
+ import { NativeMergeInsertBuilder } from "./native";
3
+ /** A builder used to create and run a merge insert operation */
4
+ export declare class MergeInsertBuilder {
5
+ #private;
6
+ /** Construct a MergeInsertBuilder. __Internal use only.__ */
7
+ constructor(native: NativeMergeInsertBuilder);
8
+ /**
9
+ * Rows that exist in both the source table (new data) and
10
+ * the target table (old data) will be updated, replacing
11
+ * the old row with the corresponding matching row.
12
+ *
13
+ * If there are multiple matches then the behavior is undefined.
14
+ * Currently this causes multiple copies of the row to be created
15
+ * but that behavior is subject to change.
16
+ *
17
+ * An optional condition may be specified. If it is, then only
18
+ * matched rows that satisfy the condtion will be updated. Any
19
+ * rows that do not satisfy the condition will be left as they
20
+ * are. Failing to satisfy the condition does not cause a
21
+ * "matched row" to become a "not matched" row.
22
+ *
23
+ * The condition should be an SQL string. Use the prefix
24
+ * target. to refer to rows in the target table (old data)
25
+ * and the prefix source. to refer to rows in the source
26
+ * table (new data).
27
+ *
28
+ * For example, "target.last_update < source.last_update"
29
+ */
30
+ whenMatchedUpdateAll(options?: {
31
+ where: string;
32
+ }): MergeInsertBuilder;
33
+ /**
34
+ * Rows that exist only in the source table (new data) should
35
+ * be inserted into the target table.
36
+ */
37
+ whenNotMatchedInsertAll(): MergeInsertBuilder;
38
+ /**
39
+ * Rows that exist only in the target table (old data) will be
40
+ * deleted. An optional condition can be provided to limit what
41
+ * data is deleted.
42
+ *
43
+ * @param options.where - An optional condition to limit what data is deleted
44
+ */
45
+ whenNotMatchedBySourceDelete(options?: {
46
+ where: string;
47
+ }): MergeInsertBuilder;
48
+ /**
49
+ * Executes the merge insert operation
50
+ *
51
+ * Nothing is returned but the `Table` is updated
52
+ */
53
+ execute(data: Data): Promise<void>;
54
+ }
package/dist/merge.js ADDED
@@ -0,0 +1,64 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.MergeInsertBuilder = void 0;
4
+ const arrow_1 = require("./arrow");
5
+ /** A builder used to create and run a merge insert operation */
6
+ class MergeInsertBuilder {
7
+ #native;
8
+ /** Construct a MergeInsertBuilder. __Internal use only.__ */
9
+ constructor(native) {
10
+ this.#native = native;
11
+ }
12
+ /**
13
+ * Rows that exist in both the source table (new data) and
14
+ * the target table (old data) will be updated, replacing
15
+ * the old row with the corresponding matching row.
16
+ *
17
+ * If there are multiple matches then the behavior is undefined.
18
+ * Currently this causes multiple copies of the row to be created
19
+ * but that behavior is subject to change.
20
+ *
21
+ * An optional condition may be specified. If it is, then only
22
+ * matched rows that satisfy the condtion will be updated. Any
23
+ * rows that do not satisfy the condition will be left as they
24
+ * are. Failing to satisfy the condition does not cause a
25
+ * "matched row" to become a "not matched" row.
26
+ *
27
+ * The condition should be an SQL string. Use the prefix
28
+ * target. to refer to rows in the target table (old data)
29
+ * and the prefix source. to refer to rows in the source
30
+ * table (new data).
31
+ *
32
+ * For example, "target.last_update < source.last_update"
33
+ */
34
+ whenMatchedUpdateAll(options) {
35
+ return new MergeInsertBuilder(this.#native.whenMatchedUpdateAll(options?.where));
36
+ }
37
+ /**
38
+ * Rows that exist only in the source table (new data) should
39
+ * be inserted into the target table.
40
+ */
41
+ whenNotMatchedInsertAll() {
42
+ return new MergeInsertBuilder(this.#native.whenNotMatchedInsertAll());
43
+ }
44
+ /**
45
+ * Rows that exist only in the target table (old data) will be
46
+ * deleted. An optional condition can be provided to limit what
47
+ * data is deleted.
48
+ *
49
+ * @param options.where - An optional condition to limit what data is deleted
50
+ */
51
+ whenNotMatchedBySourceDelete(options) {
52
+ return new MergeInsertBuilder(this.#native.whenNotMatchedBySourceDelete(options?.where));
53
+ }
54
+ /**
55
+ * Executes the merge insert operation
56
+ *
57
+ * Nothing is returned but the `Table` is updated
58
+ */
59
+ async execute(data) {
60
+ const buffer = await (0, arrow_1.fromDataToBuffer)(data);
61
+ await this.#native.execute(buffer);
62
+ }
63
+ }
64
+ exports.MergeInsertBuilder = MergeInsertBuilder;
package/dist/native.d.ts CHANGED
@@ -5,12 +5,14 @@
5
5
 
6
6
  /** A description of an index currently configured on a column */
7
7
  export interface IndexConfig {
8
+ /** The name of the index */
9
+ name: string
8
10
  /** The type of the index */
9
11
  indexType: string
10
12
  /**
11
13
  * The columns in the index
12
14
  *
13
- * Currently this is always an array of size 1. In the future there may
15
+ * Currently this is always an array of size 1. In the future there may
14
16
  * be more columns to represent composite indices.
15
17
  */
16
18
  columns: Array<string>
@@ -72,9 +74,21 @@ export interface AddColumnsSql {
72
74
  */
73
75
  valueSql: string
74
76
  }
77
+ export interface IndexStatistics {
78
+ /** The number of rows indexed by the index */
79
+ numIndexedRows: number
80
+ /** The number of rows not indexed */
81
+ numUnindexedRows: number
82
+ /** The type of the index */
83
+ indexType?: string
84
+ /** The metadata for each index */
85
+ indices: Array<IndexMetadata>
86
+ }
87
+ export interface IndexMetadata {
88
+ metricType?: string
89
+ indexType?: string
90
+ }
75
91
  export interface ConnectionOptions {
76
- apiKey?: string
77
- hostOverride?: string
78
92
  /**
79
93
  * (For LanceDB OSS only): The interval, in seconds, at which to check for
80
94
  * updates to the table from other processes. If None, then consistency is not
@@ -138,12 +152,20 @@ export class Index {
138
152
  export class RecordBatchIterator {
139
153
  next(): Promise<Buffer | null>
140
154
  }
155
+ /** A builder used to create and run a merge insert operation */
156
+ export class NativeMergeInsertBuilder {
157
+ whenMatchedUpdateAll(condition?: string | undefined | null): NativeMergeInsertBuilder
158
+ whenNotMatchedInsertAll(): NativeMergeInsertBuilder
159
+ whenNotMatchedBySourceDelete(filter?: string | undefined | null): NativeMergeInsertBuilder
160
+ execute(buf: Buffer): Promise<void>
161
+ }
141
162
  export class Query {
142
163
  onlyIf(predicate: string): void
143
164
  select(columns: Array<[string, string]>): void
144
165
  limit(limit: number): void
145
166
  nearestTo(vector: Float32Array): VectorQuery
146
167
  execute(maxBatchLength?: number | undefined | null): Promise<RecordBatchIterator>
168
+ explainPlan(verbose: boolean): Promise<string>
147
169
  }
148
170
  export class VectorQuery {
149
171
  column(column: string): void
@@ -156,8 +178,10 @@ export class VectorQuery {
156
178
  select(columns: Array<[string, string]>): void
157
179
  limit(limit: number): void
158
180
  execute(maxBatchLength?: number | undefined | null): Promise<RecordBatchIterator>
181
+ explainPlan(verbose: boolean): Promise<string>
159
182
  }
160
183
  export class Table {
184
+ name: string
161
185
  display(): string
162
186
  isOpen(): boolean
163
187
  close(): void
@@ -179,4 +203,6 @@ export class Table {
179
203
  restore(): Promise<void>
180
204
  optimize(olderThanMs?: number | undefined | null): Promise<OptimizeStats>
181
205
  listIndices(): Promise<Array<IndexConfig>>
206
+ indexStats(indexName: string): Promise<IndexStatistics | null>
207
+ mergeInsert(on: Array<string>): NativeMergeInsertBuilder
182
208
  }
package/dist/native.js CHANGED
@@ -233,17 +233,33 @@ switch (platform) {
233
233
  }
234
234
  break;
235
235
  case 'arm':
236
- localFileExisted = existsSync(join(__dirname, 'lancedb.linux-arm-gnueabihf.node'));
237
- try {
238
- if (localFileExisted) {
239
- nativeBinding = require('./lancedb.linux-arm-gnueabihf.node');
236
+ if (isMusl()) {
237
+ localFileExisted = existsSync(join(__dirname, 'lancedb.linux-arm-musleabihf.node'));
238
+ try {
239
+ if (localFileExisted) {
240
+ nativeBinding = require('./lancedb.linux-arm-musleabihf.node');
241
+ }
242
+ else {
243
+ nativeBinding = require('@lancedb/lancedb-linux-arm-musleabihf');
244
+ }
240
245
  }
241
- else {
242
- nativeBinding = require('@lancedb/lancedb-linux-arm-gnueabihf');
246
+ catch (e) {
247
+ loadError = e;
243
248
  }
244
249
  }
245
- catch (e) {
246
- loadError = e;
250
+ else {
251
+ localFileExisted = existsSync(join(__dirname, 'lancedb.linux-arm-gnueabihf.node'));
252
+ try {
253
+ if (localFileExisted) {
254
+ nativeBinding = require('./lancedb.linux-arm-gnueabihf.node');
255
+ }
256
+ else {
257
+ nativeBinding = require('@lancedb/lancedb-linux-arm-gnueabihf');
258
+ }
259
+ }
260
+ catch (e) {
261
+ loadError = e;
262
+ }
247
263
  }
248
264
  break;
249
265
  case 'riscv64':
@@ -303,10 +319,11 @@ if (!nativeBinding) {
303
319
  }
304
320
  throw new Error(`Failed to load native binding`);
305
321
  }
306
- const { Connection, Index, RecordBatchIterator, Query, VectorQuery, Table, WriteMode } = nativeBinding;
322
+ const { Connection, Index, RecordBatchIterator, NativeMergeInsertBuilder, Query, VectorQuery, Table, WriteMode } = nativeBinding;
307
323
  module.exports.Connection = Connection;
308
324
  module.exports.Index = Index;
309
325
  module.exports.RecordBatchIterator = RecordBatchIterator;
326
+ module.exports.NativeMergeInsertBuilder = NativeMergeInsertBuilder;
310
327
  module.exports.Query = Query;
311
328
  module.exports.VectorQuery = VectorQuery;
312
329
  module.exports.Table = Table;
package/dist/query.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { Table as ArrowTable, type IntoVector, RecordBatch } from "./arrow";
2
+ import { type IvfPqOptions } from "./indices";
2
3
  import { RecordBatchIterator as NativeBatchIterator, Query as NativeQuery, Table as NativeTable, VectorQuery as NativeVectorQuery } from "./native";
3
4
  export declare class RecordBatchIterator implements AsyncIterator<RecordBatch> {
4
5
  private promisedInner?;
@@ -19,9 +20,10 @@ export interface QueryExecutionOptions {
19
20
  maxBatchLength?: number;
20
21
  }
21
22
  /** Common methods supported by all query types */
22
- export declare class QueryBase<NativeQueryType extends NativeQuery | NativeVectorQuery, QueryType> implements AsyncIterable<RecordBatch> {
23
- protected inner: NativeQueryType;
24
- protected constructor(inner: NativeQueryType);
23
+ export declare class QueryBase<NativeQueryType extends NativeQuery | NativeVectorQuery> implements AsyncIterable<RecordBatch> {
24
+ protected inner: NativeQueryType | Promise<NativeQueryType>;
25
+ protected constructor(inner: NativeQueryType | Promise<NativeQueryType>);
26
+ protected doCall(fn: (inner: NativeQueryType) => void): void;
25
27
  /**
26
28
  * A filter statement to be applied to this query.
27
29
  *
@@ -34,7 +36,13 @@ export declare class QueryBase<NativeQueryType extends NativeQuery | NativeVecto
34
36
  * Filtering performance can often be improved by creating a scalar index
35
37
  * on the filter column(s).
36
38
  */
37
- where(predicate: string): QueryType;
39
+ where(predicate: string): this;
40
+ /**
41
+ * A filter statement to be applied to this query.
42
+ * @alias where
43
+ * @deprecated Use `where` instead
44
+ */
45
+ filter(predicate: string): this;
38
46
  /**
39
47
  * Return only the specified columns.
40
48
  *
@@ -65,14 +73,14 @@ export declare class QueryBase<NativeQueryType extends NativeQuery | NativeVecto
65
73
  * uses `Object.entries` which should preserve the insertion order of the object. However,
66
74
  * object insertion order is easy to get wrong and `Map` is more foolproof.
67
75
  */
68
- select(columns: string[] | Map<string, string> | Record<string, string> | string): QueryType;
76
+ select(columns: string[] | Map<string, string> | Record<string, string> | string): this;
69
77
  /**
70
78
  * Set the maximum number of results to return.
71
79
  *
72
80
  * By default, a plain search has no limit. If this method is not
73
81
  * called then every valid row from the table will be returned.
74
82
  */
75
- limit(limit: number): QueryType;
83
+ limit(limit: number): this;
76
84
  protected nativeExecute(options?: Partial<QueryExecutionOptions>): Promise<NativeBatchIterator>;
77
85
  /**
78
86
  * Execute the query and return the results as an @see {@link AsyncIterator}
@@ -91,6 +99,21 @@ export declare class QueryBase<NativeQueryType extends NativeQuery | NativeVecto
91
99
  toArrow(options?: Partial<QueryExecutionOptions>): Promise<ArrowTable>;
92
100
  /** Collect the results as an array of objects. */
93
101
  toArray(options?: Partial<QueryExecutionOptions>): Promise<any[]>;
102
+ /**
103
+ * Generates an explanation of the query execution plan.
104
+ *
105
+ * @example
106
+ * import * as lancedb from "@lancedb/lancedb"
107
+ * const db = await lancedb.connect("./.lancedb");
108
+ * const table = await db.createTable("my_table", [
109
+ * { vector: [1.1, 0.9], id: "1" },
110
+ * ]);
111
+ * const plan = await table.query().nearestTo([0.5, 0.2]).explainPlan();
112
+ *
113
+ * @param verbose - If true, provides a more detailed explanation. Defaults to false.
114
+ * @returns A Promise that resolves to a string containing the query execution plan explanation.
115
+ */
116
+ explainPlan(verbose?: boolean): Promise<string>;
94
117
  }
95
118
  /**
96
119
  * An interface for a query that can be executed
@@ -104,8 +127,8 @@ export interface ExecutableQuery {
104
127
  *
105
128
  * This builder can be reused to execute the query many times.
106
129
  */
107
- export declare class VectorQuery extends QueryBase<NativeVectorQuery, VectorQuery> {
108
- constructor(inner: NativeVectorQuery);
130
+ export declare class VectorQuery extends QueryBase<NativeVectorQuery> {
131
+ constructor(inner: NativeVectorQuery | Promise<NativeVectorQuery>);
109
132
  /**
110
133
  * Set the number of partitions to search (probe)
111
134
  *
@@ -153,7 +176,7 @@ export declare class VectorQuery extends QueryBase<NativeVectorQuery, VectorQuer
153
176
  *
154
177
  * By default "l2" is used.
155
178
  */
156
- distanceType(distanceType: string): VectorQuery;
179
+ distanceType(distanceType: Required<IvfPqOptions>["distanceType"]): VectorQuery;
157
180
  /**
158
181
  * A multiplier to control how many additional rows are taken during the refine step
159
182
  *
@@ -217,7 +240,7 @@ export declare class VectorQuery extends QueryBase<NativeVectorQuery, VectorQuer
217
240
  bypassVectorIndex(): VectorQuery;
218
241
  }
219
242
  /** A builder for LanceDB queries. */
220
- export declare class Query extends QueryBase<NativeQuery, Query> {
243
+ export declare class Query extends QueryBase<NativeQuery> {
221
244
  constructor(tbl: NativeTable);
222
245
  /**
223
246
  * Find the nearest vectors to the given query vector.
package/dist/query.js CHANGED
@@ -62,6 +62,18 @@ class QueryBase {
62
62
  this.inner = inner;
63
63
  // intentionally empty
64
64
  }
65
+ // call a function on the inner (either a promise or the actual object)
66
+ doCall(fn) {
67
+ if (this.inner instanceof Promise) {
68
+ this.inner = this.inner.then((inner) => {
69
+ fn(inner);
70
+ return inner;
71
+ });
72
+ }
73
+ else {
74
+ fn(this.inner);
75
+ }
76
+ }
65
77
  /**
66
78
  * A filter statement to be applied to this query.
67
79
  *
@@ -75,9 +87,17 @@ class QueryBase {
75
87
  * on the filter column(s).
76
88
  */
77
89
  where(predicate) {
78
- this.inner.onlyIf(predicate);
90
+ this.doCall((inner) => inner.onlyIf(predicate));
79
91
  return this;
80
92
  }
93
+ /**
94
+ * A filter statement to be applied to this query.
95
+ * @alias where
96
+ * @deprecated Use `where` instead
97
+ */
98
+ filter(predicate) {
99
+ return this.where(predicate);
100
+ }
81
101
  /**
82
102
  * Return only the specified columns.
83
103
  *
@@ -122,7 +142,9 @@ class QueryBase {
122
142
  else {
123
143
  columnTuples = Object.entries(columns);
124
144
  }
125
- this.inner.select(columnTuples);
145
+ this.doCall((inner) => {
146
+ inner.select(columnTuples);
147
+ });
126
148
  return this;
127
149
  }
128
150
  /**
@@ -132,11 +154,16 @@ class QueryBase {
132
154
  * called then every valid row from the table will be returned.
133
155
  */
134
156
  limit(limit) {
135
- this.inner.limit(limit);
157
+ this.doCall((inner) => inner.limit(limit));
136
158
  return this;
137
159
  }
138
160
  nativeExecute(options) {
139
- return this.inner.execute(options?.maxBatchLength);
161
+ if (this.inner instanceof Promise) {
162
+ return this.inner.then((inner) => inner.execute(options?.maxBatchLength));
163
+ }
164
+ else {
165
+ return this.inner.execute(options?.maxBatchLength);
166
+ }
140
167
  }
141
168
  /**
142
169
  * Execute the query and return the results as an @see {@link AsyncIterator}
@@ -160,7 +187,14 @@ class QueryBase {
160
187
  /** Collect the results as an Arrow @see {@link ArrowTable}. */
161
188
  async toArrow(options) {
162
189
  const batches = [];
163
- for await (const batch of new RecordBatchIterable(this.inner, options)) {
190
+ let inner;
191
+ if (this.inner instanceof Promise) {
192
+ inner = await this.inner;
193
+ }
194
+ else {
195
+ inner = this.inner;
196
+ }
197
+ for await (const batch of new RecordBatchIterable(inner, options)) {
164
198
  batches.push(batch);
165
199
  }
166
200
  return new arrow_1.Table(batches);
@@ -171,6 +205,28 @@ class QueryBase {
171
205
  const tbl = await this.toArrow(options);
172
206
  return tbl.toArray();
173
207
  }
208
+ /**
209
+ * Generates an explanation of the query execution plan.
210
+ *
211
+ * @example
212
+ * import * as lancedb from "@lancedb/lancedb"
213
+ * const db = await lancedb.connect("./.lancedb");
214
+ * const table = await db.createTable("my_table", [
215
+ * { vector: [1.1, 0.9], id: "1" },
216
+ * ]);
217
+ * const plan = await table.query().nearestTo([0.5, 0.2]).explainPlan();
218
+ *
219
+ * @param verbose - If true, provides a more detailed explanation. Defaults to false.
220
+ * @returns A Promise that resolves to a string containing the query execution plan explanation.
221
+ */
222
+ async explainPlan(verbose = false) {
223
+ if (this.inner instanceof Promise) {
224
+ return this.inner.then((inner) => inner.explainPlan(verbose));
225
+ }
226
+ else {
227
+ return this.inner.explainPlan(verbose);
228
+ }
229
+ }
174
230
  }
175
231
  exports.QueryBase = QueryBase;
176
232
  /**
@@ -205,7 +261,7 @@ class VectorQuery extends QueryBase {
205
261
  * you the desired recall.
206
262
  */
207
263
  nprobes(nprobes) {
208
- this.inner.nprobes(nprobes);
264
+ super.doCall((inner) => inner.nprobes(nprobes));
209
265
  return this;
210
266
  }
211
267
  /**
@@ -218,7 +274,7 @@ class VectorQuery extends QueryBase {
218
274
  * whose data type is a fixed-size-list of floats.
219
275
  */
220
276
  column(column) {
221
- this.inner.column(column);
277
+ super.doCall((inner) => inner.column(column));
222
278
  return this;
223
279
  }
224
280
  /**
@@ -236,7 +292,7 @@ class VectorQuery extends QueryBase {
236
292
  * By default "l2" is used.
237
293
  */
238
294
  distanceType(distanceType) {
239
- this.inner.distanceType(distanceType);
295
+ super.doCall((inner) => inner.distanceType(distanceType));
240
296
  return this;
241
297
  }
242
298
  /**
@@ -269,7 +325,7 @@ class VectorQuery extends QueryBase {
269
325
  * distance between the query vector and the actual uncompressed vector.
270
326
  */
271
327
  refineFactor(refineFactor) {
272
- this.inner.refineFactor(refineFactor);
328
+ super.doCall((inner) => inner.refineFactor(refineFactor));
273
329
  return this;
274
330
  }
275
331
  /**
@@ -293,7 +349,7 @@ class VectorQuery extends QueryBase {
293
349
  * factor can often help restore some of the results lost by post filtering.
294
350
  */
295
351
  postfilter() {
296
- this.inner.postfilter();
352
+ super.doCall((inner) => inner.postfilter());
297
353
  return this;
298
354
  }
299
355
  /**
@@ -306,7 +362,7 @@ class VectorQuery extends QueryBase {
306
362
  * calculate your recall to select an appropriate value for nprobes.
307
363
  */
308
364
  bypassVectorIndex() {
309
- this.inner.bypassVectorIndex();
365
+ super.doCall((inner) => inner.bypassVectorIndex());
310
366
  return this;
311
367
  }
312
368
  }
@@ -354,8 +410,39 @@ class Query extends QueryBase {
354
410
  * a default `limit` of 10 will be used. @see {@link Query#limit}
355
411
  */
356
412
  nearestTo(vector) {
357
- const vectorQuery = this.inner.nearestTo(Float32Array.from(vector));
358
- return new VectorQuery(vectorQuery);
413
+ if (this.inner instanceof Promise) {
414
+ const nativeQuery = this.inner.then(async (inner) => {
415
+ if (vector instanceof Promise) {
416
+ const arr = await vector.then((v) => Float32Array.from(v));
417
+ return inner.nearestTo(arr);
418
+ }
419
+ else {
420
+ return inner.nearestTo(Float32Array.from(vector));
421
+ }
422
+ });
423
+ return new VectorQuery(nativeQuery);
424
+ }
425
+ if (vector instanceof Promise) {
426
+ const res = (async () => {
427
+ try {
428
+ const v = await vector;
429
+ const arr = Float32Array.from(v);
430
+ //
431
+ // biome-ignore lint/suspicious/noExplicitAny: we need to get the `inner`, but js has no package scoping
432
+ const value = this.nearestTo(arr);
433
+ const inner = value.inner;
434
+ return inner;
435
+ }
436
+ catch (e) {
437
+ return Promise.reject(e);
438
+ }
439
+ })();
440
+ return new VectorQuery(res);
441
+ }
442
+ else {
443
+ const vectorQuery = this.inner.nearestTo(Float32Array.from(vector));
444
+ return new VectorQuery(vectorQuery);
445
+ }
359
446
  }
360
447
  }
361
448
  exports.Query = Query;
@@ -0,0 +1,28 @@
1
+ /// <reference types="node" />
2
+ import { type AxiosResponse } from "axios";
3
+ import { Table as ArrowTable } from "../arrow";
4
+ import { VectorQuery } from "../query";
5
+ export declare class RestfulLanceDBClient {
6
+ #private;
7
+ constructor(dbName: string, apiKey: string, region: string, hostOverride?: string, connectionTimeout?: number, readTimeout?: number);
8
+ get session(): import("axios").AxiosInstance;
9
+ get url(): string;
10
+ get headers(): {
11
+ [key: string]: string;
12
+ };
13
+ isOpen(): boolean;
14
+ private checkNotClosed;
15
+ close(): void;
16
+ get(uri: string, params?: Record<string, any>): Promise<any>;
17
+ post(uri: string, body?: any): Promise<any>;
18
+ post(uri: string, body: any, additional: {
19
+ config?: {
20
+ responseType: "arraybuffer";
21
+ };
22
+ headers?: Record<string, string>;
23
+ params?: Record<string, string>;
24
+ }): Promise<Buffer>;
25
+ listTables(limit?: number, pageToken?: string): Promise<string[]>;
26
+ query(tableName: string, query: VectorQuery): Promise<ArrowTable>;
27
+ static checkStatus(response: AxiosResponse): void;
28
+ }