@lancedb/lancedb 0.42.0-beta.2 → 0.42.0-beta.21

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/arrow.js CHANGED
@@ -1070,7 +1070,9 @@ async function fromBufferToRecordBatch(data) {
1070
1070
  * Create a buffer containing a single record batch
1071
1071
  */
1072
1072
  async function fromRecordBatchToBuffer(batch) {
1073
- const writer = new apache_arrow_1.RecordBatchFileWriter().writeAll([batch]);
1073
+ // Arrow writers require data types from their own library instance.
1074
+ const table = (0, sanitize_1.sanitizeTable)({ schema: batch.schema, batches: [batch] });
1075
+ const writer = new apache_arrow_1.RecordBatchFileWriter().writeAll(table);
1074
1076
  return Buffer.from(await writer.toUint8Array());
1075
1077
  }
1076
1078
  /**
package/dist/blob.d.ts CHANGED
@@ -124,6 +124,8 @@ export declare function blob(name: string, options?: BlobOptions): Field;
124
124
  * field's storage type.
125
125
  */
126
126
  export declare function isBlobField(field: Field): boolean;
127
+ /** @ignore */
128
+ export declare function isBlobDescriptorField(field: Field): boolean;
127
129
  /**
128
130
  * A lazy handle to blob bytes. Create one with {@link Table.fetchBlobFiles}.
129
131
  *
@@ -179,6 +181,15 @@ export type BlobReadOptions = {
179
181
  };
180
182
  /** @ignore */
181
183
  export declare function runWithSignal<T>(signal: AbortSignal | undefined, run: (signal: AbortSignal | undefined) => Promise<T>): Promise<T>;
184
+ /** One row-specific range for {@link Table.fetchBlobRanges}. */
185
+ export type BlobRangeRequest = {
186
+ /** A row ID from a query with row IDs enabled. */
187
+ rowId: bigint | number;
188
+ /** Byte offset from the beginning of the logical blob, as a uint64. */
189
+ offset: bigint;
190
+ /** Number of bytes to read, as a uint64. Zero returns an empty non-null value. */
191
+ length: bigint;
192
+ };
182
193
  /** A half-open byte range `[start, end)` for {@link BlobFile.readRanges}. */
183
194
  export type BlobRange = {
184
195
  start: bigint;
package/dist/blob.js CHANGED
@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
5
5
  exports.BlobFile = void 0;
6
6
  exports.blob = blob;
7
7
  exports.isBlobField = isBlobField;
8
+ exports.isBlobDescriptorField = isBlobDescriptorField;
8
9
  exports.runWithSignal = runWithSignal;
9
10
  exports.normalizeBlobInput = normalizeBlobInput;
10
11
  exports.blobToRead = blobToRead;
@@ -82,6 +83,32 @@ function blob(name, options = {}) {
82
83
  function isBlobField(field) {
83
84
  return field.metadata?.get("ARROW:extension:name") === BLOB_V2_EXTENSION_NAME;
84
85
  }
86
+ /** @ignore */
87
+ function isBlobDescriptorField(field) {
88
+ // Native descriptor scans replace the logical extension metadata. Require
89
+ // both the encoding marker and the v2 layout to exclude v1 and plain structs.
90
+ if (field.metadata?.get("lance-encoding:blob") !== "true" ||
91
+ !apache_arrow_1.DataType.isStruct(field.type)) {
92
+ return false;
93
+ }
94
+ const children = field.type.children;
95
+ const integers = [
96
+ ["kind", 8],
97
+ ["position", 64],
98
+ ["size", 64],
99
+ ["blob_id", 32],
100
+ ];
101
+ return (children.length === 5 &&
102
+ integers.every(([name, width], index) => {
103
+ const child = children[index];
104
+ return (child.name === name &&
105
+ apache_arrow_1.DataType.isInt(child.type) &&
106
+ !child.type.isSigned &&
107
+ child.type.bitWidth === width);
108
+ }) &&
109
+ children[4].name === "blob_uri" &&
110
+ apache_arrow_1.DataType.isUtf8(children[4].type));
111
+ }
85
112
  /**
86
113
  * A lazy handle to blob bytes. Create one with {@link Table.fetchBlobFiles}.
87
114
  *
@@ -0,0 +1,31 @@
1
+ /** Per-run retention; omission inherits selected table/branch then deployment policy. */
2
+ export interface CleanupOptions {
3
+ /** Minimum old-version age in seconds. Zero is explicit, not omitted. */
4
+ minAgeSeconds?: number;
5
+ }
6
+ /** Version-deletion outcome. Best-effort auxiliary sweeps are excluded. */
7
+ export interface CleanupResult {
8
+ formatVersion: number;
9
+ minAgeSeconds: number;
10
+ /** False after uncertain retry/recovery; both counts are then null. */
11
+ statisticsComplete: boolean;
12
+ oldVersions: number | null;
13
+ bytesRemoved: number | null;
14
+ /** Failed object deletions, if measured. Successful removals are retained. */
15
+ failedDeletes: number | null;
16
+ }
17
+ /** Read-only deletion estimates; no job or deletion snapshot is reserved. */
18
+ export interface CleanupPlan {
19
+ formatVersion: number;
20
+ sourceVersion: number;
21
+ minAgeSeconds: number;
22
+ cutoffMillis: number;
23
+ versionsToRemove: number;
24
+ bytesToRemove: number;
25
+ }
26
+ /** @internal */
27
+ export declare function decodeCleanupPlan(value: unknown): CleanupPlan;
28
+ /** @internal */
29
+ export declare function validateCleanupOptions(options?: CleanupOptions): void;
30
+ /** @internal */
31
+ export declare function decodeCleanupResult(value: unknown): CleanupResult;
@@ -0,0 +1,80 @@
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.decodeCleanupPlan = decodeCleanupPlan;
6
+ exports.validateCleanupOptions = validateCleanupOptions;
7
+ exports.decodeCleanupResult = decodeCleanupResult;
8
+ /** @internal */
9
+ function decodeCleanupPlan(value) {
10
+ if (typeof value !== "object" || value === null)
11
+ throw new Error("invalid cleanup preview");
12
+ const plan = value;
13
+ if (plan.format_version !== 1 ||
14
+ [
15
+ "source_version",
16
+ "min_age_seconds",
17
+ "cutoff_millis",
18
+ "versions_to_remove",
19
+ "bytes_to_remove",
20
+ ].some((key) => !Number.isSafeInteger(plan[key]) ||
21
+ (key !== "cutoff_millis" && plan[key] < 0))) {
22
+ throw new Error("unsupported or invalid cleanup preview");
23
+ }
24
+ return {
25
+ formatVersion: 1,
26
+ sourceVersion: plan.source_version,
27
+ minAgeSeconds: plan.min_age_seconds,
28
+ cutoffMillis: plan.cutoff_millis,
29
+ versionsToRemove: plan.versions_to_remove,
30
+ bytesToRemove: plan.bytes_to_remove,
31
+ };
32
+ }
33
+ /** @internal */
34
+ function validateCleanupOptions(options) {
35
+ if (options !== undefined &&
36
+ (typeof options !== "object" || options === null || Array.isArray(options))) {
37
+ throw new Error("cleanup options must be an object");
38
+ }
39
+ for (const key of Object.keys(options ?? {})) {
40
+ if (key !== "minAgeSeconds")
41
+ throw new Error(`Unknown cleanup option: ${key}`);
42
+ }
43
+ const age = options?.minAgeSeconds;
44
+ if (age !== undefined && (!Number.isSafeInteger(age) || age < 0)) {
45
+ throw new Error("minAgeSeconds must be a nonnegative safe integer");
46
+ }
47
+ }
48
+ /** @internal */
49
+ function decodeCleanupResult(value) {
50
+ if (typeof value !== "object" || value === null)
51
+ throw new Error("invalid cleanup result");
52
+ const result = value;
53
+ const counts = [result.old_versions ?? null, result.bytes_removed ?? null];
54
+ const failed = result.failed_deletes ?? null;
55
+ if (failed !== null &&
56
+ (!Number.isSafeInteger(failed) ||
57
+ failed < 0 ||
58
+ result.statistics_complete !== true)) {
59
+ throw new Error("invalid cleanup failed-deletion measurement");
60
+ }
61
+ if (result.format_version !== 1 ||
62
+ typeof result.statistics_complete !== "boolean" ||
63
+ !Number.isSafeInteger(result.min_age_seconds) ||
64
+ result.min_age_seconds < 0 ||
65
+ counts.some((count) => count !== null &&
66
+ (!Number.isSafeInteger(count) || count < 0)) ||
67
+ (result.statistics_complete
68
+ ? counts.some((count) => count === null)
69
+ : counts.some((count) => count !== null))) {
70
+ throw new Error("unsupported or inconsistent cleanup result");
71
+ }
72
+ return {
73
+ formatVersion: 1,
74
+ minAgeSeconds: result.min_age_seconds,
75
+ statisticsComplete: result.statistics_complete,
76
+ oldVersions: counts[0],
77
+ bytesRemoved: counts[1],
78
+ failedDeletes: result.failed_deletes ?? null,
79
+ };
80
+ }
@@ -0,0 +1,23 @@
1
+ /** Actual committed outcome of one remote compaction job. */
2
+ export interface CompactionResult {
3
+ /** A bounded run left eligible work for another invocation. */
4
+ moreWork: boolean;
5
+ /** Some planned groups were not committed. */
6
+ partialCommit: boolean;
7
+ /** Live source rows in committed rewrite groups. */
8
+ rowsSucceeded: number;
9
+ /** Planned live rows not committed by this job. */
10
+ rowsFailed: number;
11
+ /** Percentage of planned live rows committed, from 0 to 100. */
12
+ completionPercentage: number;
13
+ /** Files added, including deletion files; null if an older worker omitted it. */
14
+ filesAdded: number | null;
15
+ /** Files removed, including deletion files; null if an older worker omitted it. */
16
+ filesRemoved: number | null;
17
+ /** Fragments added by committed rewrites; null if an older worker omitted it. */
18
+ fragmentsAdded: number | null;
19
+ /** Fragments removed by committed rewrites; null if an older worker omitted it. */
20
+ fragmentsRemoved: number | null;
21
+ }
22
+ /** @internal */
23
+ export declare function decodeCompactionResult(value: unknown): CompactionResult;
@@ -0,0 +1,21 @@
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.decodeCompactionResult = decodeCompactionResult;
6
+ /** @internal */
7
+ function decodeCompactionResult(value) {
8
+ // The Rust typed-job decoder validates the wire payload before it reaches JS.
9
+ const result = value;
10
+ return {
11
+ moreWork: result.more_work,
12
+ partialCommit: result.partial_commit,
13
+ rowsSucceeded: result.rows_succeeded,
14
+ rowsFailed: result.rows_failed,
15
+ completionPercentage: result.completion_percentage,
16
+ filesAdded: result.files_added ?? null,
17
+ filesRemoved: result.files_removed ?? null,
18
+ fragmentsAdded: result.fragments_added ?? null,
19
+ fragmentsRemoved: result.fragments_removed ?? null,
20
+ };
21
+ }
@@ -440,7 +440,7 @@ export declare abstract class Connection {
440
440
  * result, failure and event history, so there is no separate
441
441
  * connection-level call for any of them.
442
442
  */
443
- abstract openJob(jobId: string): Promise<Job>;
443
+ abstract openJob<T = void>(jobId: string): Promise<Job<T>>;
444
444
  /**
445
445
  * Iterate lazily over server-side jobs across the database's tables.
446
446
  * Use `for await...of`. Options control page size and the starting token.
@@ -518,7 +518,7 @@ export declare class LocalConnection extends Connection {
518
518
  createNamespace(namespacePath: string[], options?: Partial<CreateNamespaceOptions>): Promise<CreateNamespaceResponse>;
519
519
  dropNamespace(namespacePath: string[], options?: Partial<DropNamespaceOptions>): Promise<DropNamespaceResponse>;
520
520
  renameTable(currentName: string, newName: string, options?: RenameTableOptions): Promise<void>;
521
- openJob(jobId: string): Promise<Job>;
521
+ openJob<T = void>(jobId: string): Promise<Job<T>>;
522
522
  listJobs(options?: ListingOptions): Listing<JobInfo>;
523
523
  cancelJob(jobId: string): Promise<boolean>;
524
524
  pauseJob(jobId: string): Promise<string>;
package/dist/index.d.ts CHANGED
@@ -1,23 +1,24 @@
1
- import { Connection } from "./connection";
2
- import { ConnectNamespaceOptions, ConnectionOptions, Session } from "./native.js";
3
- import { HeaderProvider } from "./header";
1
+ import { type Connection } from "./connection";
2
+ import { type ConnectNamespaceOptions, type ConnectionOptions, type Session } from "./native.js";
3
+ import type { HeaderProvider } from "./header";
4
4
  import type { BaseTokenizer } from "./indices";
5
5
  import type { FtsToken } from "./table";
6
6
  export { MaterializedView, MaterializedViewDefinition, MaterializedViewSelect, } from "./materialized_view";
7
7
  export { ViewDescription } from "./view";
8
8
  export { JsHeaderProvider as NativeJsHeaderProvider } from "./native.js";
9
9
  export { instrumentLanceDbMetrics } from "./otel";
10
- export { AddColumnsSql, ConnectionOptions, ConnectNamespaceOptions, IndexStatistics, IndexConfig, ClientConfig, TimeoutConfig, RetryConfig, TlsConfig, OptimizeStats, CompactionStats, RemovalStats, TableStatistics, FragmentStatistics, FragmentSummaryStats, Tags, TagContents, BranchContents, MergeResult, AddResult, AddColumnsResult, RefreshColumnResult, FunctionErrors, FunctionErrorsOptions, FunctionErrorRecord, FunctionErrorFragment, RefreshMaterializedViewResult, AlterColumnsResult, UpdateFieldMetadataResult, DeleteResult, DropColumnsResult, UpdateResult, SplitCalculatedOptions, SplitRandomOptions, SplitHashOptions, SplitSequentialOptions, ShuffleOptions, OAuthConfig as NativeOAuthConfig, } from "./native.js";
10
+ export { AddColumnsSql, ConnectionOptions, ConnectNamespaceOptions, IndexStatistics, IndexConfig, ClientConfig, TimeoutConfig, RetryConfig, TlsConfig, OptimizeStats, CompactionStats, RemovalStats, TableStatistics, FragmentStatistics, FragmentSummaryStats, Tags, TagContents, BranchContents, MergeResult, AddResult, AddColumnsResult, RefreshColumnOptions, FunctionRefreshPlanningConfig, FunctionRefreshPodResources, FunctionRetryPolicy, FunctionWorkerResourceBudget, RefreshColumnResult, FunctionErrors, FunctionErrorsOptions, FunctionErrorRecord, FunctionErrorFragment, RefreshMaterializedViewResult, AlterColumnsResult, UpdateFieldMetadataResult, DeleteResult, DropColumnsResult, UpdateResult, SplitCalculatedOptions, SplitRandomOptions, SplitHashOptions, SplitSequentialOptions, ShuffleOptions, OAuthConfig as NativeOAuthConfig, } from "./native.js";
11
11
  export { makeArrowTable, makeJsonField, MakeArrowTableOptions, Data, VectorColumnOptions, } from "./arrow";
12
12
  export { blob, isBlobField, BlobFile } from "./blob";
13
- export type { BlobData, BlobInput, BlobOptions, BlobRange, BlobReadOptions, BlobUri, } from "./blob";
13
+ export type { BlobData, BlobInput, BlobOptions, BlobRange, BlobRangeRequest, BlobReadOptions, BlobUri, } from "./blob";
14
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
- export type { JobProgress, JobProgressCallback } from "./job";
17
+ export type { JobProgress, JobProgressCallback, JobState, JobWaitOptions, } from "./job";
18
+ export type { FunctionProfile, FunctionProfileKind, FunctionProfileOptions, FunctionProfileStatus, FunctionProfileWaitOptions, } from "./profiling";
18
19
  export { AutoQuery, ExecutableQuery, Query, QueryBase, VectorQuery, TakeQuery, AnalyzePlanDistributedMetrics, BlobMode, QueryExecutionOptions, ColumnOrdering, FullTextSearchOptions, RecordBatchIterator, FullTextQuery, MatchQuery, PhraseQuery, BoostQuery, MultiMatchQuery, BooleanQuery, FullTextQueryType, Operator, Occur, } from "./query";
19
- export { Index, IndexOptions, IvfPqOptions, IvfRqOptions, IvfFlatOptions, HnswPqOptions, HnswSqOptions, FtsOptions, BaseTokenizer, } from "./indices";
20
- 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
+ export { Index, IndexOptions, IvfPqOptions, IvfRqOptions, IvfFlatOptions, HnswPqOptions, HnswSqOptions, FtsOptions, RTreeOptions, BaseTokenizer, } from "./indices";
21
+ export { Table, TableDelta, TableDeltaReader, TableDeltaTransaction, DeltaVersion, FunctionColumnAutoRefreshStatus, FunctionColumnLastRefreshJob, FunctionColumnStatus, FunctionColumnVersionStatus, Branches, CreateBranchOptions, BranchColumnSummary, BranchColumnChange, BranchIndexSummary, BranchRowCountSummary, CherryPickError, BranchDiff, CherryPickPreview, CherryPickResult, AddDataOptions, UpdateOptions, OptimizeOptions, CompactionOptions, PrewarmDataOptions, Version, WriteProgress, FtsToken, TokenizeTableOptions, RTEWriteSpec, RTEStats, TableShardStats, SsTableStats, MemtableStats, ColumnAlteration, FieldMetadataUpdate, } from "./table";
21
22
  export { HeaderProvider, StaticHeaderProvider, OAuthHeaderProvider, TokenResponse, } from "./header";
22
23
  export { ClientAuthMethod, OAuthConfig, OAuthFlowType, OAuthSession, SessionLogout, SessionStatus, TokenCacheOptions, } from "./oauth";
23
24
  export { MergeInsertBuilder, WriteExecutionOptions } from "./merge";
@@ -253,3 +254,7 @@ export declare function connectNamespace(implName: "rest", config: RestNamespace
253
254
  export declare function connectNamespace(implName: string, properties: Record<string, string>, options?: Partial<ConnectNamespaceOptions>): Promise<Connection>;
254
255
  export { Catalog, CatalogOptions, DatabaseNames, connectCatalog, } from "./catalog";
255
256
  export { Listing, ListingOptions } from "./listing";
257
+ export type { CompactionResult } from "./compaction";
258
+ export type { CleanupOptions, CleanupPlan, CleanupResult } from "./cleanup";
259
+ export type { PrewarmDataPlan, PrewarmDataResult, PrewarmPruningSummary, } from "./prewarm";
260
+ export type { QueryParameters, QueryParameterValue } from "./sql";
package/dist/index.js CHANGED
@@ -2,8 +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.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;
5
+ 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.TableDelta = 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 = exports.litBool = void 0;
7
7
  exports.tokenize = tokenize;
8
8
  exports.connect = connect;
9
9
  exports.connectNamespace = connectNamespace;
@@ -57,6 +57,7 @@ var indices_1 = require("./indices");
57
57
  Object.defineProperty(exports, "Index", { enumerable: true, get: function () { return indices_1.Index; } });
58
58
  var table_1 = require("./table");
59
59
  Object.defineProperty(exports, "Table", { enumerable: true, get: function () { return table_1.Table; } });
60
+ Object.defineProperty(exports, "TableDelta", { enumerable: true, get: function () { return table_1.TableDelta; } });
60
61
  Object.defineProperty(exports, "Branches", { enumerable: true, get: function () { return table_1.Branches; } });
61
62
  var header_1 = require("./header");
62
63
  Object.defineProperty(exports, "HeaderProvider", { enumerable: true, get: function () { return header_1.HeaderProvider; } });
package/dist/indices.d.ts CHANGED
@@ -617,6 +617,17 @@ export interface FtsOptions {
617
617
  */
618
618
  blockSize?: 128 | 256;
619
619
  }
620
+ /**
621
+ * Options to create an `RTREE` index
622
+ */
623
+ export interface RTreeOptions {
624
+ /**
625
+ * The maximum number of entries in each R-tree page.
626
+ *
627
+ * Must be at least 2. The default is 4096.
628
+ */
629
+ pageSize?: number;
630
+ }
620
631
  export declare class Index {
621
632
  private readonly inner;
622
633
  private constructor();
@@ -722,6 +733,39 @@ export declare class Index {
722
733
  * full-text-search index, it matches arbitrary substrings of the raw bytes.
723
734
  */
724
735
  static fm(): Index;
736
+ /**
737
+ * Create an RTree index.
738
+ *
739
+ * An RTree index is a scalar index on a GeoArrow geometry column, that is, a
740
+ * column whose Arrow field metadata sets `ARROW:extension:name` to a GeoArrow
741
+ * type such as `geoarrow.point`, `geoarrow.polygon` or `geoarrow.wkb`. It
742
+ * stores the bounding box of each geometry and accelerates spatial filters.
743
+ *
744
+ * The index accelerates `ST_Intersects`, `ST_Contains`, `ST_Within`,
745
+ * `ST_Touches`, `ST_Crosses`, `ST_Overlaps`, `ST_Covers` and `ST_CoveredBy`
746
+ * between the indexed column and a constant geometry, in either argument
747
+ * order, for example
748
+ * `ST_Within(geom, ST_GeomFromText('POLYGON ((...))'))`, as well as
749
+ * `geom IS NULL`. These filters can be combined with other conditions using
750
+ * `AND`.
751
+ *
752
+ * See the R-tree section of https://docs.lancedb.com/indexing/scalar-index
753
+ * for storing geometry, the other spatial functions, and spatial filters on
754
+ * vector search.
755
+ *
756
+ * Remote tables send the `RTREE` index type to the server, which must
757
+ * support it.
758
+ *
759
+ * @example
760
+ * ```ts
761
+ * await table.createIndex("geom", { config: Index.rtree() });
762
+ * await table
763
+ * .query()
764
+ * .where("ST_Intersects(geom, ST_GeomFromText('POLYGON ((0 0, 4 0, 0 4, 0 0))'))")
765
+ * .toArray();
766
+ * ```
767
+ */
768
+ static rtree(options?: Partial<RTreeOptions>): Index;
725
769
  /**
726
770
  * Create a full text search index
727
771
  *
package/dist/indices.js CHANGED
@@ -125,6 +125,48 @@ class Index {
125
125
  static fm() {
126
126
  return new Index(native_1.Index.fm());
127
127
  }
128
+ /**
129
+ * Create an RTree index.
130
+ *
131
+ * An RTree index is a scalar index on a GeoArrow geometry column, that is, a
132
+ * column whose Arrow field metadata sets `ARROW:extension:name` to a GeoArrow
133
+ * type such as `geoarrow.point`, `geoarrow.polygon` or `geoarrow.wkb`. It
134
+ * stores the bounding box of each geometry and accelerates spatial filters.
135
+ *
136
+ * The index accelerates `ST_Intersects`, `ST_Contains`, `ST_Within`,
137
+ * `ST_Touches`, `ST_Crosses`, `ST_Overlaps`, `ST_Covers` and `ST_CoveredBy`
138
+ * between the indexed column and a constant geometry, in either argument
139
+ * order, for example
140
+ * `ST_Within(geom, ST_GeomFromText('POLYGON ((...))'))`, as well as
141
+ * `geom IS NULL`. These filters can be combined with other conditions using
142
+ * `AND`.
143
+ *
144
+ * See the R-tree section of https://docs.lancedb.com/indexing/scalar-index
145
+ * for storing geometry, the other spatial functions, and spatial filters on
146
+ * vector search.
147
+ *
148
+ * Remote tables send the `RTREE` index type to the server, which must
149
+ * support it.
150
+ *
151
+ * @example
152
+ * ```ts
153
+ * await table.createIndex("geom", { config: Index.rtree() });
154
+ * await table
155
+ * .query()
156
+ * .where("ST_Intersects(geom, ST_GeomFromText('POLYGON ((0 0, 4 0, 0 4, 0 0))'))")
157
+ * .toArray();
158
+ * ```
159
+ */
160
+ static rtree(options) {
161
+ const pageSize = options?.pageSize;
162
+ // napi converts a number to u32 by wrapping, so -1 would arrive as
163
+ // 4294967295; reject anything that is not a valid page size first.
164
+ if (pageSize !== undefined &&
165
+ !(Number.isInteger(pageSize) && pageSize >= 2 && pageSize <= 0xffffffff)) {
166
+ throw new Error(`RTree page_size must be at least 2, at most 4294967295, and an integer, got ${pageSize}`);
167
+ }
168
+ return new Index(native_1.Index.rtree(pageSize));
169
+ }
128
170
  /**
129
171
  * Create a full text search index
130
172
  *
package/dist/job.d.ts CHANGED
@@ -1,11 +1,14 @@
1
1
  import { Table as ArrowTable } from "apache-arrow";
2
- import { JobFailureInfo, Job as NativeJob } from "./native";
2
+ import type { JobFailureInfo, Job as NativeJob } from "./native";
3
+ import { type FunctionProfile, type FunctionProfileOptions, type FunctionProfileWaitOptions } from "./profiling";
3
4
  /** Which of a job's events {@link Job.events} returns. */
4
5
  export interface JobEventsOptions {
5
6
  /** Maximum event rows to return, up to the server maximum of 10,000. */
6
7
  limit?: number;
7
8
  /** SQL-like filter over the event columns. */
8
9
  filter?: string;
10
+ /** Opaque continuation from the preceding page's schema metadata. */
11
+ pageToken?: string;
9
12
  }
10
13
  /**
11
14
  * A forward-compatible structured progress snapshot for a server-side job.
@@ -29,6 +32,19 @@ export interface JobProgress {
29
32
  rows_skipped?: number | null;
30
33
  rows_remaining?: number | null;
31
34
  rows_failed?: number | null;
35
+ /** Maintenance work observations; rewritten rows are not committed rows. */
36
+ groups_planned?: number | null;
37
+ groups_completed?: number | null;
38
+ rows_rewritten?: number | null;
39
+ executors_targeted?: number | null;
40
+ executors_completed?: number | null;
41
+ executors_partial?: number | null;
42
+ executors_active?: number | null;
43
+ executors_failed?: number | null;
44
+ fragments_selected?: number | null;
45
+ ranges_completed?: number | null;
46
+ ranges_planned?: number | null;
47
+ bytes_read?: number | null;
32
48
  /** Execution identity and sample time used for client-side ETA derivation. */
33
49
  execution_epoch?: number | null;
34
50
  sample_at_millis?: number | null;
@@ -39,6 +55,19 @@ export interface JobProgress {
39
55
  }
40
56
  /** Callback for progress snapshots observed while waiting for a job. */
41
57
  export type JobProgressCallback = (progress: JobProgress) => void;
58
+ /** Client-side controls for waiting without cancelling the underlying job. */
59
+ export interface JobWaitOptions {
60
+ /**
61
+ * Maximum wait in milliseconds, including status requests and polling backoff.
62
+ * Must be a nonnegative safe integer. Omit to wait indefinitely; zero allows
63
+ * only an immediately ready result.
64
+ */
65
+ timeoutMs?: number;
66
+ /** Observe progress using the same poller that waits for completion. */
67
+ onProgress?: JobProgressCallback;
68
+ }
69
+ /** Detailed lifecycle state. Unrecognized future values remain strings. */
70
+ export type JobState = "created" | "queued" | "in_progress" | "succeeded" | "failed" | "canceled" | "timed_out" | (string & {});
42
71
  /**
43
72
  * A handle to an operation that may still be running.
44
73
  *
@@ -56,9 +85,10 @@ export type JobProgressCallback = (progress: JobProgress) => void;
56
85
  *
57
86
  * @hideconstructor
58
87
  */
59
- export declare class Job {
88
+ export declare class Job<T = void> {
60
89
  private readonly inner;
61
- constructor(inner: NativeJob);
90
+ private readonly resultDecoder?;
91
+ constructor(inner: NativeJob, resultDecoder?: (value: unknown) => T);
62
92
  /**
63
93
  * Identifies the operation on the server that is running it.
64
94
  *
@@ -68,6 +98,27 @@ export declare class Job {
68
98
  * durable resume tokens.
69
99
  */
70
100
  get id(): string | null;
101
+ /**
102
+ * Identity of the selected attempt last observed by this handle.
103
+ * For operation handles, `refresh()` or `status()` can select a different
104
+ * attempt while `id` stays unchanged. Save this value after refreshing and
105
+ * use it throughout paged diagnostics. Local IDs cannot be reopened on a server.
106
+ */
107
+ get jobId(): string | null;
108
+ /** Root of the explicit retry lineage, when reported. */
109
+ get operationId(): string | null;
110
+ /** One-based attempt ordinal. Worker replacement does not increment it. */
111
+ get attempt(): number | null;
112
+ /** Immediate predecessor attempt, when reported. */
113
+ get retryOf(): string | null;
114
+ /** Detailed state last observed; unknown values never establish success. */
115
+ get lifecycleState(): JobState | null;
116
+ /** Source snapshot pinned for this attempt, when reported. */
117
+ get sourceTableVersion(): number | null;
118
+ /** Most recent execution's fencing token, when reported. */
119
+ get executionEpoch(): number | null;
120
+ /** Refresh and return the detailed lifecycle state. */
121
+ statusTyped(): Promise<JobState>;
71
122
  /** The last observed lifecycle state, without contacting the backend. */
72
123
  get state(): string | null;
73
124
  /**
@@ -112,10 +163,22 @@ export declare class Job {
112
163
  * synchronous observer: its return value is ignored and not awaited. If it
113
164
  * throws, the error is logged with `console.warn` and waiting continues; a
114
165
  * callback exception does not reject `wait`.
166
+ *
167
+ * Pass an options object to set a client-side timeout. Expiry rejects with an
168
+ * error and stops this wait, including pending status requests and backoff.
169
+ * The operation continues; use the same handle to wait again. Registry jobs
170
+ * can also be reopened with `Connection.openJob`; query IDs cannot.
171
+ *
172
+ * @example
173
+ * ```ts
174
+ * const result = await job.wait({ timeoutMs: 60_000, onProgress: console.log });
175
+ * ```
115
176
  */
116
- wait(progressCallback?: JobProgressCallback): Promise<void>;
177
+ wait(optionsOrProgress?: JobWaitOptions | JobProgressCallback): Promise<T>;
117
178
  /** Request cancellation. Cancelling a finished operation is a no-op. */
118
179
  cancel(): Promise<void>;
180
+ /** Select this exact attempt's pinned successor. Requires backend support. */
181
+ retry(): Promise<Job<T>>;
119
182
  /**
120
183
  * Ask the backend for this job's current state, and for a server-side job
121
184
  * its full record, then cache it for the getters above.
@@ -136,6 +199,56 @@ export declare class Job {
136
199
  * `updated_by`, `emitted_from`, `emitted_by`, and `claim_entity` columns.
137
200
  */
138
201
  events(options?: JobEventsOptions): Promise<ArrowTable>;
202
+ /** Walk retained history one page at a time using the server's continuation. */
203
+ history(options?: JobEventsOptions): AsyncGenerator<ArrowTable>;
204
+ /**
205
+ * Request a profile of a running Enterprise Function worker session.
206
+ * Returns the accepted identity without waiting for recording to finish.
207
+ * Requires System Operate permission and server profiling support. The server
208
+ * pins the worker, Python session and execution epoch. One capture per job
209
+ * can be active. Captures add workload-dependent overhead.
210
+ *
211
+ * GPU tracing requires initialized PyTorch CUDA/CUPTI. CPU sampling requires
212
+ * readable per-thread procfs and is unavailable in dedicated sandboxes.
213
+ *
214
+ * @example
215
+ * ```ts
216
+ * const profile = await job.captureProfile("worker-id", {
217
+ * kind: "gpu", durationSeconds: 2,
218
+ * });
219
+ * await job.waitForProfile(profile.profileId, { timeoutMs: 60_000 });
220
+ * await job.exportProfile(profile.profileId, "gpu.trace.json");
221
+ * ```
222
+ */
223
+ captureProfile(workerId: string, options?: FunctionProfileOptions): Promise<FunctionProfile>;
224
+ /**
225
+ * Fetch capture identity and status, including retained lookup after refresh.
226
+ * Failed captures return status "failed" with the server's error reason.
227
+ * This never changes the parent job's cached state.
228
+ */
229
+ profileStatus(profileId: string): Promise<FunctionProfile>;
230
+ /**
231
+ * Wait for a capture with a configurable timeout and polling cadence.
232
+ * Defaults to 60 seconds with two seconds between requests. A timeout stops
233
+ * only this wait; the capture and Function refresh continue. A failed capture
234
+ * rejects with its server-reported reason. Keep its ID to wait again.
235
+ */
236
+ waitForProfile(profileId: string, options?: FunctionProfileWaitOptions): Promise<FunctionProfile>;
237
+ /**
238
+ * Retrieve a completed capture's actual JSON: speedscope for CPU,
239
+ * tracemalloc for Python allocations, or Chrome Trace Event JSON for GPU.
240
+ * Truncation flags are preserved. Retention is at most one hour and eight
241
+ * captures per job, until earlier scratch reclamation or archival.
242
+ * Permission, expired-artifact and unsupported-server errors propagate.
243
+ */
244
+ profileArtifact(profileId: string): Promise<Record<string, unknown>>;
245
+ /**
246
+ * Write a completed capture's JSON after successful retrieval. Open CPU
247
+ * exports in speedscope and GPU exports in Perfetto. GPU activity durations
248
+ * can overlap and are not utilization; Python operator attribution and GPU
249
+ * allocation stacks are excluded. Filesystem errors propagate to the caller.
250
+ */
251
+ exportProfile(profileId: string, path: string): Promise<void>;
139
252
  private lastProgress;
140
253
  private enrichProgress;
141
254
  /**