@functional-systems/lambdadb 0.3.3 → 0.3.4-dev.0

package/src/client.ts

@@ -675,7 +675,7 @@ class CollectionDocs {
   }
 
   /**
-   * Get presigned URL and metadata for bulk upload (up to 200MB).
+   * Get presigned URL and metadata for bulk upload (up to 200MB). Not supported for collections with managed embedding vector fields.
    */
   async getBulkUpsert(options?: RequestOptions) {
     return unwrapAsync(
@@ -688,7 +688,7 @@ class CollectionDocs {
   }
 
   /**
-   * Get presigned URL and metadata for bulk upload (Safe: returns Result instead of throwing).
+   * Get presigned URL and metadata for bulk upload (Safe: returns Result instead of throwing). Not supported for collections with managed embedding vector fields.
    */
   async getBulkUpsertSafe(
     options?: RequestOptions,
@@ -701,7 +701,7 @@ class CollectionDocs {
   }
 
   /**
-   * Trigger bulk upsert with an object key from getBulkUpsert().
+   * Trigger bulk upsert with an object key from getBulkUpsert(). Not supported for collections with managed embedding vector fields.
    */
   async bulkUpsert(
     body: BulkUpsertInput,
@@ -720,7 +720,7 @@ class CollectionDocs {
   }
 
   /**
-   * Trigger bulk upsert (Safe: returns Result instead of throwing).
+   * Trigger bulk upsert (Safe: returns Result instead of throwing). Not supported for collections with managed embedding vector fields.
    */
   async bulkUpsertSafe(
     body: BulkUpsertInput,
@@ -734,7 +734,7 @@ class CollectionDocs {
   }
 
   /**
-   * Bulk upsert documents in one call (up to 200MB). Abstracts getBulkUpsert,
+   * Bulk upsert documents in one call (up to 200MB). Not supported for collections with managed embedding vector fields. Abstracts getBulkUpsert,
    * S3 upload via presigned URL, and bulkUpsert. Use this for better DX when
    * you have a document list; use getBulkUpsert + bulkUpsert for low-level control.
    */
@@ -770,7 +770,7 @@ class CollectionDocs {
   }
 
   /**
-   * Bulk upsert documents in one call (Safe: returns Result instead of throwing).
+   * Bulk upsert documents in one call (Safe: returns Result instead of throwing). Not supported for collections with managed embedding vector fields.
    * May return Error for local failures (payload size, upload). API errors use GetBulkUpsertDocsError or BulkUpsertDocsError.
    */
   async bulkUpsertDocsSafe(

package/src/funcs/collectionsDocsBulkUpsert.ts

@@ -27,7 +27,7 @@ import { APICall, APIPromise } from "../types/async.js";
 import { Result } from "../types/fp.js";
 
 /**
- * Bulk upsert documents into a collection. Note that the maximum supported object size is 200MB.
+ * Bulk upsert documents into a collection. Note that the maximum supported object size is 200MB. Bulk upsert is not supported for collections with managed embedding vector fields.
  */
 export function collectionsDocsBulkUpsert(
   client: LambdaDBCore,

package/src/funcs/collectionsDocsGetBulkUpsert.ts

@@ -26,7 +26,7 @@ import { APICall, APIPromise } from "../types/async.js";
 import { Result } from "../types/fp.js";
 
 /**
- * Request required info to upload documents.
+ * Request required info to upload documents. Bulk upsert is not supported for collections with managed embedding vector fields.
  */
 export function collectionsDocsGetBulkUpsert(
   client: LambdaDBCore,
@@ -35,6 +35,7 @@ export function collectionsDocsGetBulkUpsert(
 ): APIPromise<
   Result<
     operations.GetBulkUpsertDocsResponse,
+    | errors.BadRequestError
     | errors.UnauthenticatedError
     | errors.ResourceNotFoundError
     | errors.TooManyRequestsError
@@ -64,6 +65,7 @@ async function $do(
   [
     Result<
       operations.GetBulkUpsertDocsResponse,
+      | errors.BadRequestError
       | errors.UnauthenticatedError
       | errors.ResourceNotFoundError
       | errors.TooManyRequestsError
@@ -152,7 +154,7 @@ async function $do(
 
   const doResult = await client._do(req, {
     context,
-    errorCodes: ["401", "404", "429", "4XX", "500", "5XX"],
+    errorCodes: ["400", "401", "404", "429", "4XX", "500", "5XX"],
     retryConfig: context.retryConfig,
     retryCodes: context.retryCodes,
   });
@@ -167,6 +169,7 @@ async function $do(
 
   const [result] = await M.match<
     operations.GetBulkUpsertDocsResponse,
+    | errors.BadRequestError
     | errors.UnauthenticatedError
     | errors.ResourceNotFoundError
     | errors.TooManyRequestsError
@@ -181,6 +184,7 @@ async function $do(
     | SDKValidationError
   >(
     M.json(200, operations.GetBulkUpsertDocsResponse$inboundSchema),
+    M.jsonErr(400, errors.BadRequestError$inboundSchema),
     M.jsonErr(401, errors.UnauthenticatedError$inboundSchema),
     M.jsonErr(404, errors.ResourceNotFoundError$inboundSchema),
     M.jsonErr(429, errors.TooManyRequestsError$inboundSchema),

package/src/models/indexconfigsunion.ts

@@ -47,15 +47,59 @@ export type Similarity = ClosedEnum<typeof Similarity>;
 export type IndexConfigsVector = {
   type: "vector";
   /**
-   * Vector dimensions.
+   * Set to false or omit for unmanaged vector fields.
+   */
+  managedEmbedding?: false | undefined;
+  /**
+   * Vector dimensions for unmanaged vector fields.
    */
   dimensions: number;
   /**
-   * Vector similarity metric.
+   * Vector similarity metric for unmanaged vector fields.
+   */
+  similarity?: Similarity | undefined;
+};
+
+export const EmbeddingProvider = {
+  Openai: "openai",
+} as const;
+export type EmbeddingProvider = ClosedEnum<typeof EmbeddingProvider>;
+
+/**
+ * Managed embedding configuration for vector fields.
+ */
+export type EmbeddingConfig = {
+  /**
+   * Embedding provider.
+   */
+  provider: EmbeddingProvider;
+  /**
+   * Embedding model name. See /guides/collections/managed-embeddings for the current supported providers and models.
+   */
+  model: string;
+  /**
+   * Source text field name used to generate embeddings.
+   */
+  sourceField: string;
+  /**
+   * Resolved embedding dimensions. Optional in requests and resolved in stored collection metadata.
+   */
+  dimensions?: number | undefined;
+  /**
+   * Resolved vector similarity metric. Optional in requests and resolved in stored collection metadata.
    */
   similarity?: Similarity | undefined;
 };
 
+export type IndexConfigsManagedEmbeddingVector = {
+  type: "vector";
+  /**
+   * Managed embedding vector field.
+   */
+  managedEmbedding: true;
+  embedding: EmbeddingConfig;
+};
+
 export const Analyzer = {
   Standard: "standard",
   Korean: "korean",
@@ -75,6 +119,7 @@ export type IndexConfigsText = {
 export type IndexConfigsUnion =
   | IndexConfigsText
   | IndexConfigsVector
+  | IndexConfigsManagedEmbeddingVector
   | (IndexConfigs & { type: "keyword" })
   | (IndexConfigs & { type: "long" })
   | (IndexConfigs & { type: "double" })
@@ -181,12 +226,14 @@ export const IndexConfigsVector$inboundSchema: z.ZodType<
   unknown
 > = z.object({
   type: z.literal("vector"),
+  managedEmbedding: nullToUndefined(z.literal(false).optional()),
   dimensions: z.number().int(),
   similarity: nullToUndefined(Similarity$inboundSchema.default("cosine")),
 });
 /** @internal */
 export type IndexConfigsVector$Outbound = {
   type: "vector";
+  managedEmbedding?: false | undefined;
   dimensions: number;
   similarity: string;
 };
@@ -198,6 +245,7 @@ export const IndexConfigsVector$outboundSchema: z.ZodType<
   IndexConfigsVector
 > = z.object({
   type: z.literal("vector"),
+  managedEmbedding: z.literal(false).optional(),
   dimensions: z.number().int(),
   similarity: Similarity$outboundSchema.default("cosine"),
 });
@@ -219,6 +267,112 @@ export function indexConfigsVectorFromJSON(
   );
 }
 
+/** @internal */
+export const EmbeddingProvider$inboundSchema: z.ZodNativeEnum<
+  typeof EmbeddingProvider
+> = z.nativeEnum(EmbeddingProvider);
+/** @internal */
+export const EmbeddingProvider$outboundSchema: z.ZodNativeEnum<
+  typeof EmbeddingProvider
+> = EmbeddingProvider$inboundSchema;
+
+/** @internal */
+export const EmbeddingConfig$inboundSchema: z.ZodType<
+  EmbeddingConfig,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  provider: EmbeddingProvider$inboundSchema,
+  model: z.string(),
+  sourceField: z.string(),
+  dimensions: nullToUndefined(z.number().int().optional()),
+  similarity: nullToUndefined(Similarity$inboundSchema.default("cosine")),
+});
+/** @internal */
+export type EmbeddingConfig$Outbound = {
+  provider: string;
+  model: string;
+  sourceField: string;
+  dimensions?: number | undefined;
+  similarity?: string | undefined;
+};
+
+/** @internal */
+export const EmbeddingConfig$outboundSchema: z.ZodType<
+  EmbeddingConfig$Outbound,
+  z.ZodTypeDef,
+  EmbeddingConfig
+> = z.object({
+  provider: EmbeddingProvider$outboundSchema,
+  model: z.string(),
+  sourceField: z.string(),
+  dimensions: z.number().int().optional(),
+  similarity: Similarity$outboundSchema.optional(),
+});
+
+export function embeddingConfigToJSON(
+  embeddingConfig: EmbeddingConfig,
+): string {
+  return JSON.stringify(EmbeddingConfig$outboundSchema.parse(embeddingConfig));
+}
+export function embeddingConfigFromJSON(
+  jsonString: string,
+): SafeParseResult<EmbeddingConfig, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => EmbeddingConfig$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'EmbeddingConfig' from JSON`,
+  );
+}
+
+/** @internal */
+export const IndexConfigsManagedEmbeddingVector$inboundSchema: z.ZodType<
+  IndexConfigsManagedEmbeddingVector,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  type: z.literal("vector"),
+  managedEmbedding: z.literal(true),
+  embedding: z.lazy(() => EmbeddingConfig$inboundSchema),
+});
+/** @internal */
+export type IndexConfigsManagedEmbeddingVector$Outbound = {
+  type: "vector";
+  managedEmbedding: true;
+  embedding: EmbeddingConfig$Outbound;
+};
+
+/** @internal */
+export const IndexConfigsManagedEmbeddingVector$outboundSchema: z.ZodType<
+  IndexConfigsManagedEmbeddingVector$Outbound,
+  z.ZodTypeDef,
+  IndexConfigsManagedEmbeddingVector
+> = z.object({
+  type: z.literal("vector"),
+  managedEmbedding: z.literal(true),
+  embedding: z.lazy(() => EmbeddingConfig$outboundSchema),
+});
+
+export function indexConfigsManagedEmbeddingVectorToJSON(
+  indexConfigsManagedEmbeddingVector: IndexConfigsManagedEmbeddingVector,
+): string {
+  return JSON.stringify(
+    IndexConfigsManagedEmbeddingVector$outboundSchema.parse(
+      indexConfigsManagedEmbeddingVector,
+    ),
+  );
+}
+export function indexConfigsManagedEmbeddingVectorFromJSON(
+  jsonString: string,
+): SafeParseResult<IndexConfigsManagedEmbeddingVector, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) =>
+      IndexConfigsManagedEmbeddingVector$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'IndexConfigsManagedEmbeddingVector' from JSON`,
+  );
+}
+
 /** @internal */
 export const Analyzer$inboundSchema: z.ZodNativeEnum<typeof Analyzer> = z
   .nativeEnum(Analyzer);
@@ -276,6 +430,7 @@ export const IndexConfigsUnion$inboundSchema: z.ZodType<
 > = z.union([
   z.lazy(() => IndexConfigsText$inboundSchema),
   z.lazy(() => IndexConfigsVector$inboundSchema),
+  z.lazy(() => IndexConfigsManagedEmbeddingVector$inboundSchema),
   z.lazy(() => IndexConfigs$inboundSchema).and(
     z.object({ type: z.literal("keyword") }),
   ),
@@ -300,6 +455,7 @@ export const IndexConfigsUnion$inboundSchema: z.ZodType<
 export type IndexConfigsUnion$Outbound =
   | IndexConfigsText$Outbound
   | IndexConfigsVector$Outbound
+  | IndexConfigsManagedEmbeddingVector$Outbound
   | (IndexConfigs$Outbound & { type: "keyword" })
   | (IndexConfigs$Outbound & { type: "long" })
   | (IndexConfigs$Outbound & { type: "double" })
@@ -316,6 +472,7 @@ export const IndexConfigsUnion$outboundSchema: z.ZodType<
 > = z.union([
   z.lazy(() => IndexConfigsText$outboundSchema),
   z.lazy(() => IndexConfigsVector$outboundSchema),
+  z.lazy(() => IndexConfigsManagedEmbeddingVector$outboundSchema),
   z.lazy(() => IndexConfigs$outboundSchema).and(
     z.object({ type: z.literal("keyword") }),
   ),

package/src/models/operations/querycollection.ts

@@ -15,7 +15,7 @@ export type QueryCollectionRequestBody = {
    */
   size?: number | undefined;
   /**
-   * Query object.
+   * Query object. For managed embedding vector fields, use knn.queryText. For unmanaged vector fields, use knn.queryVector.
    */
   query: { [k: string]: any };
   /**

package/src/models/operations/updatedocs.ts

@@ -7,7 +7,7 @@ import { remap as remap$ } from "../../lib/primitives.js";
 
 export type UpdateDocsRequestBody = {
   /**
-   * A list of documents to update. Each document must contain 'id' field to be updated.
+   * A list of documents to update. Each document must contain 'id' field to be updated. For managed embedding vector fields, omit the managed vector field and update only the configured source text field.
    */
   docs: Array<{ [k: string]: any }>;
 };

package/src/models/operations/upsertdocs.ts

@@ -7,7 +7,7 @@ import { remap as remap$ } from "../../lib/primitives.js";
 
 export type UpsertDocsRequestBody = {
   /**
-   * A list of documents to upsert.
+   * A list of documents to upsert. For managed embedding vector fields, omit the managed vector field and provide only the configured source text field.
    */
   docs: Array<{ [k: string]: any }>;
 };

package/src/sdk/docs.ts

@@ -47,7 +47,7 @@ export class Docs extends ClientSDK {
   }
 
   /**
-   * Request required info to upload documents.
+   * Request required info to upload documents. Bulk upsert is not supported for collections with managed embedding vector fields.
    */
   async getBulkUpsert(
     request: operations.GetBulkUpsertDocsRequest,
@@ -61,7 +61,7 @@ export class Docs extends ClientSDK {
   }
 
   /**
-   * Bulk upsert documents into a collection. Note that the maximum supported object size is 200MB.
+   * Bulk upsert documents into a collection. Note that the maximum supported object size is 200MB. Bulk upsert is not supported for collections with managed embedding vector fields.
    */
   async bulkUpsert(
     request: operations.BulkUpsertDocsRequest,

package/src/types/errors.ts

@@ -94,4 +94,6 @@ export type FetchDocsError = UpdateCollectionError;
 export type BulkUpsertDocsError = UpdateCollectionError;
 
 /** Errors that can occur when getting bulk upsert docs info. */
-export type GetBulkUpsertDocsError = ListCollectionsError;
+export type GetBulkUpsertDocsError =
+  | errors.BadRequestError
+  | ListCollectionsError;

package/src/types/public.ts

@@ -48,6 +48,9 @@ export type { GetBulkUpsertDocsResponse } from "../models/operations/getbulkupse
 // ---- Models referenced by request/response bodies ----
 export type {
   IndexConfigsUnion,
+  IndexConfigsManagedEmbeddingVector,
+  EmbeddingConfig,
+  EmbeddingProvider,
   PartitionConfig,
   PartitionFilter,
   FieldsSelectorUnion,

package/test/public-api.test.mjs

@@ -83,6 +83,144 @@ test("public client lists collections with project URL, auth header, and Date co
   assert.equal(result.collections[0].createdAt.toISOString(), "2023-11-14T22:13:20.000Z");
 });
 
+test("public client supports managed embedding vector index configs", async () => {
+  const managedIndexConfigs = {
+    body: {
+      type: "text",
+      analyzers: ["english"],
+    },
+    bodyEmbedding: {
+      type: "vector",
+      managedEmbedding: true,
+      embedding: {
+        provider: "openai",
+        model: "text-embedding-3-small",
+        sourceField: "body",
+      },
+    },
+  };
+
+  const { calls, client } = createClient((call) => {
+    assert.equal(call.method, "POST");
+    assert.equal(call.url.pathname, "/projects/project-one/collections");
+    assert.deepEqual(JSON.parse(call.body), {
+      collectionName: "semantic-items",
+      indexConfigs: {
+        body: {
+          type: "text",
+          analyzers: ["english"],
+        },
+        bodyEmbedding: {
+          type: "vector",
+          managedEmbedding: true,
+          embedding: {
+            provider: "openai",
+            model: "text-embedding-3-small",
+            sourceField: "body",
+          },
+        },
+      },
+    });
+
+    return jsonResponse(
+      {
+        collection: collectionFixture("semantic-items", {
+          indexConfigs: {
+            ...managedIndexConfigs,
+            bodyEmbedding: {
+              ...managedIndexConfigs.bodyEmbedding,
+              embedding: {
+                ...managedIndexConfigs.bodyEmbedding.embedding,
+                dimensions: 1536,
+                similarity: "cosine",
+              },
+            },
+          },
+        }),
+      },
+      { status: 202 },
+    );
+  });
+
+  const result = await client.createCollection({
+    collectionName: "semantic-items",
+    indexConfigs: managedIndexConfigs,
+  });
+
+  assert.equal(calls.length, 1);
+  assert.equal(
+    result.collection.indexConfigs.bodyEmbedding.embedding.dimensions,
+    1536,
+  );
+  assert.equal(
+    result.collection.indexConfigs.bodyEmbedding.embedding.similarity,
+    "cosine",
+  );
+});
+
+test("collection query supports managed embedding queryText KNN payloads", async () => {
+  const { calls, client } = createClient((call) => {
+    assert.equal(call.method, "POST");
+    assert.equal(call.url.pathname, "/projects/project-one/collections/items/query");
+    assert.deepEqual(JSON.parse(call.body), {
+      size: 10,
+      query: {
+        knn: {
+          field: "bodyEmbedding",
+          queryText: "refund policy",
+          k: 10,
+        },
+      },
+      consistentRead: false,
+      includeVectors: false,
+    });
+
+    return jsonResponse({
+      took: 3,
+      maxScore: 0.98,
+      total: 1,
+      docs: [{ collection: "items", score: 0.98, doc: { id: "a" } }],
+      isDocsInline: true,
+      docsUrl: null,
+    });
+  });
+
+  const result = await client.collection("items").query({
+    size: 10,
+    query: {
+      knn: {
+        field: "bodyEmbedding",
+        queryText: "refund policy",
+        k: 10,
+      },
+    },
+  });
+
+  assert.equal(calls.length, 1);
+  assert.equal(result.total, 1);
+});
+
+test("getBulkUpsertSafe exposes managed embedding unsupported bad requests", async () => {
+  const { client } = createClient((call) => {
+    assert.equal(call.method, "GET");
+    assert.equal(call.url.pathname, "/projects/project-one/collections/items/docs/bulk-upsert");
+
+    return jsonResponse(
+      { message: "Bulk upsert is not supported for collections with managed embedding fields" },
+      { status: 400 },
+    );
+  });
+
+  const result = await client.collection("items").docs.getBulkUpsertSafe();
+
+  assert.equal(result.ok, false);
+  assert.ok(result.error instanceof BadRequestError);
+  assert.equal(
+    result.error.data$.message,
+    "Bulk upsert is not supported for collections with managed embedding fields",
+  );
+});
+
 test("public pagination helpers collect all collection pages", async () => {
   const { calls, client } = createClient((call, index) => {
     if (index === 0) {

package/tsconfig.json

@@ -14,9 +14,8 @@
     "declarationMap": true,
     "sourceMap": true,
     "outDir": ".",
-    
+    "rootDir": "src",
 
-    // https://github.com/tsconfig/bases/blob/a1bf7c0fa2e094b068ca3e1448ca2ece4157977e/bases/strictest.json
     "strict": true,
     "allowUnusedLabels": false,
     "allowUnreachableCode": false,