# @functional-systems/lambdadb 中文文档

规范地址：https://npmcn.com/package/%40functional-systems/lambdadb/

版本：0\.12\.0
npm 元数据更新时间：2026-11-06T09:50:46.799Z
中文译文更新时间：2026-11-15T17:04:27.062Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40functional-systems/lambdadb
原文对照：https://npmcn.com/package/%40functional-systems/lambdadb/?lang=original
项目主页：https://github.com/lambdadb/lambdadb-typescript-client#readme
源码仓库：https://github.com/lambdadb/lambdadb-typescript-client

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.4 MB，919 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2025-08-06T04:20:12.074Z
- 最新版本发布：2026-11-06T09:50:46.385Z
- 近 30 天下载量：5820（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：59（近 12 个月 56 个）

## 中文简介

开发者友好型和型号安全型 SDK 专门适应杠杆 _蓝巴达德布_ API (英语).

## 安装

```sh
npm install @functional-systems/lambdadb
```

也可以使用：`pnpm add @functional-systems/lambdadb`、`yarn add @functional-systems/lambdadb`、`bun add @functional-systems/lambdadb`

## README

# 羊巴达b

开发者友好型和型号安全型 SDK 专门适应杠杆 _蓝巴达德布_ API (英语).

[![](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

## 内容提要

LambdaDB API: LambdaDB 开放 API spec

## 目录

-   [羊巴达b](https://npmcn.com/package/%40functional-systems/lambdadb/#readme-lambdadb)
    -   [SDK 安装](https://npmcn.com/package/%40functional-systems/lambdadb/#readme-sdk-installation)
    -   [所需资源](https://npmcn.com/package/%40functional-systems/lambdadb/#readme-requirements)
    -   [SDK 示例使用法](https://npmcn.com/package/%40functional-systems/lambdadb/#readme-sdk-example-usage)
    -   [数据版本](https://npmcn.com/package/%40functional-systems/lambdadb/#readme-data-versioning)
    -   [相容性](https://npmcn.com/package/%40functional-systems/lambdadb/#readme-qdrant-compatibility)
    -   [认证](https://npmcn.com/package/%40functional-systems/lambdadb/#readme-authentication)
    -   [现有资源和业务](https://npmcn.com/package/%40functional-systems/lambdadb/#readme-available-resources-and-operations)
    -   [独立职能](https://npmcn.com/package/%40functional-systems/lambdadb/#readme-standalone-functions)
    -   [检索](https://npmcn.com/package/%40functional-systems/lambdadb/#readme-retries)
    -   [处理错误](https://npmcn.com/package/%40functional-systems/lambdadb/#readme-error-handling)
    -   [服务器选择](https://npmcn.com/package/%40functional-systems/lambdadb/#readme-server-selection)
    -   [自定义 HTTP 客户端](https://npmcn.com/package/%40functional-systems/lambdadb/#readme-custom-http-client)
    -   [调试](https://npmcn.com/package/%40functional-systems/lambdadb/#readme-debugging)
-   [发展](https://npmcn.com/package/%40functional-systems/lambdadb/#readme-development)
    -   [成熟度](https://npmcn.com/package/%40functional-systems/lambdadb/#readme-maturity)
    -   [捐款](https://npmcn.com/package/%40functional-systems/lambdadb/#readme-contributions)

## SDK 安装

SDK可以安装其中之一 [无](https://www.npmjs.com/), (中文(简体) ), [小时](https://pnpm.io/), (中文(简体) ), [包头](https://bun.sh/) 或者说 [线条](https://classic.yarnpkg.com/en/) 软件包管理器.

### 国家预防机制

```bash
npm add @functional-systems/lambdadb
```

### 菲律宾

```bash
pnpm add @functional-systems/lambdadb
```

### 阿宝

```bash
bun add @functional-systems/lambdadb
```

### 雅伦

```bash
yarn add @functional-systems/lambdadb
```

> \[注\] 此软件包由CommonJS和ES模块(ESM)支持发布.

## 所需资源

对于支持的 JavaScript 运行时间, 请参考 [运行时间.md](https://npmcn.com/package/%40functional-systems/lambdadb/RUNTIMES.md)。 。 。 .

## SDK 示例使用法

我们建议 **收藏范围客户端** (单位:千美元)`LambdaDBClient`:你得到一个手柄,一次一次一次的收集,然后调用方法而不通过 `collectionName` 每一个请求.

### 建议:LambdaDB客户端(收集范围)

客户端连接到 `{baseUrl}/projects/{projectName}`默认值 : **基数Url** `https://api.lambdadb.ai`, (中文(简体) ), **工程Name** `playground`覆盖 `baseUrl` 财务报告和审定财务报表 `projectName` 当创建客户端时.

```typescript
import { LambdaDBClient } from "@functional-systems/lambdadb";

const client = new LambdaDBClient({
  projectApiKey: "<YOUR_PROJECT_API_KEY>",
  // Optional: baseUrl (default "https://api.lambdadb.ai"), projectName (default "playground")
});

async function run() {
  // List all collections in the project (optional: pass { size, pageToken } for pagination)
  const list = await client.listCollections();
  console.log(list); // list.collections[].createdAt etc. are Date

  // Work with a specific collection — no collectionName in every call
  const collection = client.collection("my-collection");
  await collection.get();
  await collection.docs.list({ size: 20 });
  await collection.docs.upsert({ docs: [{ id: "1", text: "hello" }] });
  // For large document sets (up to 200MB), use bulkUpsertDocs for a single-call flow.
  // Native embedding fields require caller-supplied vectors; bulk upsert never generates embeddings.
  // await collection.docs.bulkUpsertDocs({ docs: largeDocArray });
}

run();
```

### 类型脚本

从包中导入请求和响应类型,用于类型安全使用. 使用 **投入** 方法参数类型和 **回应** 类型.

```typescript
import {
  LambdaDBClient,
  type CreateCollectionInput,
  type QueryCollectionInput,
  type QueryCollectionResponse,
  type ListDocsInput,
  type ListDocsResponse,
} from "@functional-systems/lambdadb";

const client = new LambdaDBClient({ projectApiKey: "..." });
const collection = client.collection("my-collection");

// Typed list params
const params: ListDocsInput = { size: 20, pageToken: undefined };
const listResult: ListDocsResponse = await collection.docs.list(params);

// Typed query body and response (or use createQueryInput helper)
const queryBody: QueryCollectionInput = {
  query: { text: "hello" },
  size: 10,
};
const queryResult: QueryCollectionResponse = await collection.query(queryBody);
```

常见类型 : `CreateCollectionInput`, (中文(简体) ), `UpdateCollectionInput`, (中文(简体) ), `QueryCollectionInput`, (中文(简体) ), `ListDocsInput`, (中文(简体) ), `ListCollectionsInput`, (中文(简体) ), `UpsertDocsInput`, (中文(简体) ), `DeleteDocsInput`, (中文(简体) ), `FetchDocsInput`, (中文(简体) ), `BulkUpsertInput`; 响应类型,例如 `QueryCollectionResponse`, (中文(简体) ), `ListDocsResponse`, (中文(简体) ), `ListCollectionsResponseWithDates`, (中文(简体) ), `GetCollectionResponseWithDates`, (中文(简体) ), `FetchDocsResponse`, (中文(简体) ), `MessageResponse`; 数据版本类型, 如 `ReadRef`, (中文(简体) ), `BranchSource`, (中文(简体) ), `RefSource`, (中文(简体) ), `AliasTarget`, (中文(简体) ), `SnapshotDetails`, (中文(简体) ), `ParentBranchDetails`, (中文(简体) ), `BranchDetails`,以及 `TagDetails`;和模型类型,如 `CollectionResponseWithDates`, (中文(简体) ), `IndexConfigsUnion`, (中文(简体) ), `IndexConfigsManagedEmbeddingVector`, (中文(简体) ), `EmbeddingConfig`, (中文(简体) ), `PartitionConfig`, (中文(简体) ), `FieldsSelectorUnion`收集创建/列表/获取/更新并更新生命周期回复,将时间戳暴露为 `Date`。全部从主包中导出.

## 数据版本

创建收藏范围分支、标签和异名,然后选择一个参考文件 读作或写作处:

```typescript
import {
  LambdaDBClient,
  aliasRef,
  branchSource,
  tagTarget,
} from "@functional-systems/lambdadb";

const client = new LambdaDBClient({ projectApiKey: "..." });
const collection = client.collection("knowledge-base");

await collection.branches.create({
  branchName: "candidate",
  source: branchSource("main"),
});
await collection.tags.create({
  tagName: "release-001",
  source: branchSource("candidate"),
});
await collection.aliases.create({
  aliasName: "production",
  target: tagTarget("release-001"),
});

await collection.docs.upsert({
  branch: "candidate",
  docs: [{ id: "doc-1", text: "candidate content" }],
});

for await (const page of collection.docs.listPages({
  size: 50,
  ref: aliasRef("production"),
})) {
  console.log(page.docs);
}
```

指定读取或写入处保留现有的 `main` 行为. 分支创建只接受分支源; 省略 `source` 选择 `main`, (中文(简体) ), 财务报告和审定财务报表 `branchSource(name, asOf)` 支持点入时间创建。 标签创建 继续接受分支或Tag来源。 分支创建/列表回复包括 要求无效 `parentBranch: { branchId, name }`即使是空头; `main` 和没有记录的父母返回的分支 `null`。 。 。 . 见 [数据版本](https://npmcn.com/package/%40functional-systems/lambdadb/docs/data-versioning.md) 生命周期方法,安全 错误, 点入时源, 签名批量上传, 以及转移客户端 配置 。 数据版本合同由Lambadb/docs承付 `1714009a2659a18b26cb68193dd7a071fd6efb42` (单位:千美元)`reference/api/openapi.json`),它也允许 `consistentRead: true` 通过一个异形 瞄准一个分支。 删除引用的分支或标记 由异形失败 `CatalogConflictError` (HTTP语) `409`; 删除或重新瞄准 所有参考的异名。 读取通过 目标失败 `BadRequestError` (HTTP语) `400`),同时选择一个 不存在的参考失败 `ResourceNotFoundError` (HTTP语) `404`) (中文(简体) ).

49个固定文本分析器预设文件载于 [分析器](https://npmcn.com/package/%40functional-systems/lambdadb/docs/models/analyzer.md) 并使用单独的 [固定来源合同](https://npmcn.com/package/%40functional-systems/lambdadb/docs/OPENAPI_UPDATE.md#openapi-spec)。 。 。 .

### 索引字段描述

每个索引字段,包括嵌入对象的孩子,都接受可选 `description` 最多255个字符。 从不影响索引,而是被退回 仅于设定时读取。 打开 `update`,省略它保存存储 说明, `""` 清除它, 并替换一个新的值; 这是唯一的设置 用于更新可能改变的现有字段。 服务器管理 `id` 字段 不接受一个。 见 [索引连接](https://npmcn.com/package/%40functional-systems/lambdadb/docs/models/indexconfigsunion.md)。 。 。 .

```typescript
await client.createCollection({
  collectionName: "books",
  indexConfigs: {
    title: { type: "text", analyzers: ["english"], description: "Book title as printed on the cover" },
    details: {
      type: "object",
      objectIndexConfigs: { pages: { type: "long", description: "Page count" } },
    },
  },
});
```

### 查询限制

查询 `size`密度 `knn.k`贝叶斯人 `candidateSize`,以及 `rerank.candidateSize` 最多可达1000人 [固定后端合同](https://npmcn.com/package/%40functional-systems/lambdadb/docs/OPENAPI_UPDATE.md#updating-query-limits)。 。 。 . 查询结果和水合候选机构不再拥有总计64个米B 限制。 使用现有的 `docsUrl` 下载格式; 用尽 服务器共享的临时存储预算返回 HTTP 503 没有部分结果. 见 [查询大小和字节限制](https://npmcn.com/package/%40functional-systems/lambdadb/docs/native-reranking.md#query-size-and-byte-limits)。 。 。 . 脸桶保留了100个物品的限制. 获取并获取/ POP 列表支持 1000个ID/文档;列表默认为100个. 获取保留一个每节点的64 MiB JSON 预算。 见 [改为合同](https://npmcn.com/package/%40functional-systems/lambdadb/docs/OPENAPI_UPDATE.md#updating-fetch-and-list)。 。 。 . 源头对齐不会建立您的端点部署 .

### 原产地重新排序

通过一个可选的每克 `rerank` 对象 `query` 或者说 `querySafe` 与 `provider: "typesafe"` 财务报告和审定财务报表 `model: "jev-1.13.0"`,或 `provider: "cohere"` 财务报告和审定财务报表 `model: "rerank-v5.0-pro"` 编号 : `"rerank-v5.0-fast"`,加上非空白 `queryText` 和存储的 scalar 文本 `fields`。服务器管理证书。 对于TypeSafe, 选项 `criteria` 选择 2 - 10 命令的自定义描述; 省略/ 无效使用 默认标准。 联合体不接受标准. 见 [原产地重新排序](https://npmcn.com/package/%40functional-systems/lambdadb/docs/native-reranking.md) 默认/海关/Cohere 示例, 候选限制,反应字段和符合条件的倒置行为. 应用 `score` 是\[0,1\]的最后评价分数,而不是相关概率; `retrievalScore` 保留外部原始搜索分数 `doc`检查 `rerank.status` 因为后退保留了搜索分数。 发件/无件 `rerank` 保持已有的查询行为.

### 关键词方面

按索引关键字值计算匹配文档,包括数组和点数 字段路径。 查询级别 `size: 0` 返回没有文档的计数; 省略 `query` 以计算选定读取范围内的所有文档.

```typescript
const result = await client.collection("items").query({
  size: 0,
  facets: { tags: { size: 5 } },
});
for (const bucket of result.facets?.tags?.buckets ?? []) {
  console.log(bucket.value, bucket.count);
}
```

`querySafe` 接受相同的输入。 请求最多五个关键字字段,其中 每个字段有1-100个桶(省略或无效时默认为10个). 计数覆盖所有 匹配文档,与返回的文档数量无关,并存 `docsUrl` 下载。 公共类型包括: `FacetRequest`, (中文(简体) ), `FacetBucket`,以及 `FacetResult`。 。 。 .

使用包含面元特性和新建关键字的服务器部署 索引。 必须将现有数据重新插入新的收藏;旧标记和 部分索引更新不迁移格式。 见 [关键词方面](https://npmcn.com/package/%40functional-systems/lambdadb/docs/keyword-facets.md) 用于支持查询、限制和验证证据.

### 倾斜

**联合国** 使用 `listPages()` 以不将所有东西装入内存的方式在所有页面上进行排列,或者 `listAll()` 以将所有文件合并到一个单一的列表中。 每个页面是一个 API 响应; API 限制响应大小 **有效载数**,而不是根据文档数,所以每页文件数可能少于请求的 `size` 并可以因页面而异。 方法 `list()`, (中文(简体) ), `query()`,以及 `fetch()` 当 API 通过返回时, 自动解析来自预先签名的 URL 的文档 `docsUrl` (单位:千美元)`isDocsInline: false`所以,你总是得到 `docs` 在回应中.

页面符号是不透明的搜索位置,而不是快照针. 为了一个稳定 多页导出, 选择相同的不可移动标记并保留过滤器和字段 在每个页面上选择不变.

```typescript
import { LambdaDBClient } from "@functional-systems/lambdadb";

const client = new LambdaDBClient({ projectApiKey: "..." });
const collection = client.collection("my-collection");

// Page-by-page (memory efficient)
for await (const page of collection.docs.listPages({ size: 50 })) {
  console.log(page.docs.length, page.nextPageToken ?? "last page");
}

// Or load all docs (for small/medium collections)
const { docs, total } = await collection.docs.listAll({ size: 100 });
console.log(docs.length, total);
```

**收藏:** 使用 `listCollections(params?)` 可选 `size` 财务报告和审定财务报表 `pageToken`,或 `listCollectionsPages(params?)` 编号 : `listAllCollections(params?)` 将所有藏品逐行删除或取出.

```typescript
// One page
const page = await client.listCollections({ size: 20 });

// Page-by-page
for await (const page of client.listCollectionsPages({ size: 20 })) {
  console.log(page.collections.length, page.nextPageToken ?? "last");
}

// All collections
const { collections } = await client.listAllCollections({ size: 50 });
```

### 查询助手

使用 `createQueryInput()` 以构建查询参数 `collection.query()` 或者说 `collection.querySafe()`数字 :

```typescript
import { LambdaDBClient, createQueryInput } from "@functional-systems/lambdadb";

const client = new LambdaDBClient({ projectApiKey: "..." });
const collection = client.collection("my-collection");

const input = createQueryInput({ text: "hello" }, { size: 10 });
const result = await collection.query(input);
```

### 相容性

对于常见的 Qdrant JavaScript 客户端迁移路径, 请使用明确路径 Qdrant 相容性适配器 :

```typescript
import { QdrantCompatClient, models } from "@functional-systems/lambdadb/compat/qdrant";

const client = new QdrantCompatClient({
  projectApiKey: "<YOUR_PROJECT_API_KEY>",
  projectName: "playground",
});

await client.createCollection("docs", {
  vectorsConfig: new models.VectorParams({
    size: 64,
    distance: models.Distance.COSINE,
  }),
});
```

适配器覆盖了常见的稠密载体RAG子集,而不是一个完整的Qdrant 客户端替换。 见 [文件/兼容性/qdrant.md](https://npmcn.com/package/%40functional-systems/lambdadb/docs/compatibility/qdrant.md) 用于支持方法、数据映射和不支持的特性.

Live Qdrant 兼容性烟雾测试可以从本地装入证书 `.env` 文件 :

```bash
cp .env.example .env
# Fill in LAMBDADB_PROJECT_API_KEY and set LAMBDADB_RUN_LIVE_TESTS=1.
npm run test:live:qdrant
```

LangChain JS和LlamaIndex TS的外部融合烟雾测试 正在处理的假LambdaDB运输,不需要证明:

```bash
npm run test:external:qdrant
```

### 原生嵌入

原生嵌入向量字段从已配置的 JSON 生成向量 路径。 来源及其对象的祖先不需要指数声明. 声明 向量字段,将原始 JSON 写入,并查询 `knn.queryText`数字 :

```typescript
import { LambdaDBClient } from "@functional-systems/lambdadb";

const client = new LambdaDBClient({ projectApiKey: "..." });

await client.createCollection({
  collectionName: "semantic-items",
  indexConfigs: {
    bodyEmbedding: {
      type: "vector",
      embedding: {
        provider: "openai",
        model: "text-embedding-3-small",
        sources: [{ field: "article.body", type: "text" }],
      },
    },
  },
});

const collection = client.collection("semantic-items");
await collection.docs.upsert({
  docs: [{ id: "policy-1", article: { body: "Refunds are available within 30 days." } }],
});

const result = await collection.query({
  size: 10,
  query: {
    knn: {
      field: "bodyEmbedding",
      queryText: "refund policy",
      k: 10,
    },
  },
});
```

遗产 `sourceField: "article.body"` 表格仍然支持。 代码 (单位:千美元)`embed-v5.0-pro` 编号 : `embed-v5.0-fast`)也接受命令的文本和图像 `sources` 和混合 `knn.queryInputs`; 见 [命令和图像源](https://npmcn.com/package/%40functional-systems/lambdadb/docs/native-embeddings.md#ordered-and-image-sources)。 。 。 . `rerank.fields` 可以选择相同的无索引字符串路径。 添加适当的来源 当您还需要从词典中查找、过滤或排序这些字段时,您需要索引. 这需要 [本地嵌入合同](https://npmcn.com/package/%40functional-systems/lambdadb/docs/native-embeddings.md) 在已部署的端点上; 仅用一面遗留的旗帜并不能使无索引来源成为可能.

## 认证

### 常客安全计划

这个SDK在全球支持以下安全计划:

| 名称 | 类型 | 计划 | 环境变量 |
| --- | --- | --- | --- |
| `projectApiKey` | 键 | API 密钥 | `LAMBDADB_PROJECT_API_KEY` |

用 API 认证 `projectApiKey` 初始化 SDK 客户端实例时必须设置参数 。 例如:

```typescript
import { LambdaDBClient } from "@functional-systems/lambdadb";

const client = new LambdaDBClient({
  projectApiKey: "<YOUR_PROJECT_API_KEY>",
});

async function run() {
  const result = await client.listCollections();
  console.log(result);
}

run();
```

## 现有资源和业务

可用方法

### [收款](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/collections/README.md)

-   [列表](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/collections/README.md#list) - 列出现有项目中的所有收藏( 支持 pagination : `size`, (中文(简体) ), `pageToken`) (中文(简体) ). 打开 **LambdaDB 客户端** 使用情况 `listCollections(params?)`, (中文(简体) ), `listCollectionsPages(params?)`,或 `listAllCollections(params?)` 重复;收集答复包括: `createdAt`编号 :`updatedAt`编号 :`dataUpdatedAt` 作为 `Date`。 。 。 .
-   [创建](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/collections/README.md#create) - 创建一个收藏.
-   [删除](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/collections/README.md#delete) - 删除现有的收藏.
-   [起来](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/collections/README.md#get) - 获取现有收藏的元数据.
-   [更新](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/collections/README.md#update) - 配置一个收藏.
-   [查询](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/collections/README.md#query) - 以查询方式搜索收藏,并返回最相似的文档.

#### [藏书. 文档](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/docs/README.md)

-   [列表标记](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/docs/README.md#listdocs) - 列出收藏中的文档.
-   [升级](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/docs/README.md#upsert) - 将文档放入收藏中。 注意最大支持有效载荷尺寸为6MB.
-   [散装升华标记](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/docs/README.md#bulkupsertdocs) - 在一次调用(最多200MB)中将文档分批进行;当您有文档列表时,将此用于最佳 DX 。 原生嵌入场需要调用器提供向量;批量提升不会产生嵌入.
-   [获得布克 Upsert](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/docs/README.md#getbulkupsert) - 要求上传文件所需的信息。 原生嵌入场需要调用器提供向量;批量提升不会产生嵌入.
-   [块集](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/docs/README.md#bulkupsert) - 将文件集中起来 注意最大支持对象大小为200MB. 原生嵌入场需要调用器提供向量;批量提升不会产生嵌入.
-   [更新](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/docs/README.md#update) - 更新收藏中的文档。 注意最大支持有效载荷尺寸为6MB.
-   [删除](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/docs/README.md#delete) - 准确通过一个文件ID或查询过滤器删除文档.
-   [获取](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/docs/README.md#fetch) - 以文件身份从收藏中查找和退回文件.

### 遗产 API( C)`LambdaDB`(中文(简体) )

经典客户端 `LambdaDB` 仍然支持兼容性。 新代码应该更可取 `LambdaDBClient` 财务报告和审定财务报表 `client.collection(name)`。 。 。 .

```typescript
import { LambdaDB } from "@functional-systems/lambdadb";

const lambdaDB = new LambdaDB({ projectApiKey: "<YOUR_PROJECT_API_KEY>" });
const result = await lambdaDB.collections.list();
await lambdaDB.collections.docs.listDocs({ collectionName: "my-collection", size: 20 });
```

见 [文件/文件/收集/README.md](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/collections/README.md) 财务报告和审定财务报表 [文件/文件/文件/README.md](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/docs/README.md) 用于完整遗留的 API 参考.

## 独立职能

上述所有方法都作为独立功能提供。 这些 函数是用于在浏览器中运行的应用程序的理想功能,没有服务器 运行时间或应用程序捆绑大小为主的其他环境 关心。 当使用捆绑器构建您的应用程序时, 全部未使用 功能将被从最后的捆绑中排除,或者被树切除.

要了解更多独立函数, 请检查 [职能.md](https://npmcn.com/package/%40functional-systems/lambdadb/FUNCTIONS.md)。 。 。 .

现有的独立职能

-   [`collectionsCreate`](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/collections/README.md#create) - 创建一个收藏.
-   [`collectionsDelete`](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/collections/README.md#delete) - 删除现有的收藏.
-   [`collectionsDocsBulkUpsert`](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/docs/README.md#bulkupsert) - 将文件集中起来 注意最大支持对象大小为200MB. 原生嵌入场需要调用器提供向量;批量提升不会产生嵌入.
-   [`collectionsDocsDelete`](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/docs/README.md#delete) - 准确通过一个文件ID或查询过滤器删除文档.
-   [`collectionsDocsFetch`](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/docs/README.md#fetch) - 以文件身份从收藏中查找和退回文件.
-   [`collectionsDocsGetBulkUpsert`](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/docs/README.md#getbulkupsert) - 要求上传文件所需的信息。 原生嵌入场需要调用器提供向量;批量提升不会产生嵌入.
-   [`collectionsDocsListDocs`](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/docs/README.md#listdocs) - 列出收藏中的文档.
-   [`collectionsDocsUpdate`](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/docs/README.md#update) - 更新收藏中的文档。 注意最大支持有效载荷尺寸为6MB.
-   [`collectionsDocsUpsert`](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/docs/README.md#upsert) - 将文档放入收藏中。 注意最大支持有效载荷尺寸为6MB.
-   [`collectionsGet`](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/collections/README.md#get) - 获取现有收藏的元数据.
-   [`collectionsList`](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/collections/README.md#list) - 列出现有项目中的所有收藏.
-   [`collectionsQuery`](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/collections/README.md#query) - 以查询方式搜索收藏,并返回最相似的文档.
-   [`collectionsUpdate`](https://npmcn.com/package/%40functional-systems/lambdadb/docs/sdks/collections/README.md#update) - 配置一个收藏.

## 检索

重试行为由 SDK 配置 。 文档写入 API 请求使用备份 hTTP 默认重试 `429`,所有数据 `5xx` 答复(包括 `500`, (中文(简体) ), `502`, (中文(简体) ), `503`,以及 `504`),以及连接出错或运输超时。 待命 `retries` 覆盖 客户的 `retryConfig`。同样的重试设置适用于 `*Safe` 方法; 返回 a 结果不禁重试.

可重试 `429` 响应,后退执行尊重有效 `Retry-After` 头当现相. API不保证每个 `429` 包含此信头.

对于写作,错误不能证明突变没有发生. 这个 成功承诺后可能失去反应,自动重复 在SDK返回出错或成功响应前重新应用写入. 复议并不提供准确的一次执行.

在决定是否重试写前检查状态, 禁用自动 在初始通话中重复:

```typescript
import { LambdaDBClient } from "@functional-systems/lambdadb";

const client = new LambdaDBClient({
  projectApiKey: "<YOUR_PROJECT_API_KEY>",
});
const collection = client.collection("my-collection");

await collection.docs.upsert(
  { docs: [{ id: "doc-1", title: "Updated title" }] },
  { retries: { strategy: "none" } },
);
```

此选项可同时禁用 HTTP 状态和连接- 错误重试 . 仅设定 `retryConnectionErrors: false` 仍然允许重试 HTTP 答复,包括 `502` 财务报告和审定财务报表 `504`被重审 无效复试不 取消服务器侧写或确定其结果。 失败后,检查 目标分支声明并在发布前考虑操作的语义 再写一篇 SDK不自动进行这种调节.

更改一个 API 呼叫的重试策略, 通过 `retries` 在请求选项中:

```typescript
import { LambdaDBClient } from "@functional-systems/lambdadb";

const client = new LambdaDBClient({
  projectApiKey: "<YOUR_PROJECT_API_KEY>",
});

async function run() {
  const result = await client.listCollections(undefined, {
    retries: {
      strategy: "backoff",
      backoff: {
        initialInterval: 1,
        maxInterval: 50,
        exponent: 1.1,
        maxElapsedTime: 100,
      },
      retryConnectionErrors: false,
    },
  });
  console.log(result);
}

run();
```

如果您想要覆盖所有支持重试的操作的默认重试策略, 您可以在 SDK 初始化时提供重试Config :

```typescript
import { LambdaDBClient } from "@functional-systems/lambdadb";

const client = new LambdaDBClient({
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  },
  projectApiKey: "<YOUR_PROJECT_API_KEY>",
});

async function run() {
  const result = await client.listCollections();
  console.log(result);
}

run();

```

**超时和请求级别选项 :** 您可以在创建客户端或每个呼叫时设置请求超时( ms)并重试行为. 如果没有设置, 没有请求超时 。 这个 `RetryConfig` 类型从软件包中导出,用于输入您的选项.

```typescript
import { LambdaDBClient, type RetryConfig } from "@functional-systems/lambdadb";

const client = new LambdaDBClient({
  projectApiKey: "...",
  timeoutMs: 30_000,       // 30s timeout for all requests
  retryConfig: { strategy: "backoff", retryConnectionErrors: true },
});

// Override per request
await client.listCollections(undefined, { timeoutMs: 10_000, retries: { strategy: "none" } });
```

## 处理错误

[`LambdaDBError`](https://npmcn.com/package/%40functional-systems/lambdadb/src/models/errors/lambdadberror.ts) 是所有 HTTP 错误响应的基础类。 其属性如下:

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| `error.message` | `string` | 错误消息 |
| `error.statusCode` | `number` | HTTP 响应状态代码 eg `404` |
| `error.headers` | `Headers` | HTTP 响应头 |
| `error.body` | `string` | HTTP 躯体. 如果没有尸体返回, 则可以是空字符串 . |
| `error.rawResponse` | `Response` | 原始 HTTP 响应 |
| `error.retryAfter` | `string | undefined` | 可选 `Retry-After` 响应头. |
| `error.data$` |  | 可选的 一些错误可能包含结构化数据. [参见错误类](https://npmcn.com/package/%40functional-systems/lambdadb/#readme-error-classes)。 。 。 . |

### 默认方法( 在错误上投掷)

常规方法失败。 获取错误和使用 `instanceof` 到狭义的类型。 从主软件包导出出出错类 :

```typescript
import {
  LambdaDBClient,
  LambdaDBError,
  UnauthenticatedError,
  ResourceNotFoundError,
} from "@functional-systems/lambdadb";

const client = new LambdaDBClient({
  projectApiKey: "<YOUR_PROJECT_API_KEY>",
});

async function run() {
  try {
    const result = await client.listCollections();
    console.log(result);
  } catch (error) {
    if (error instanceof LambdaDBError) {
      console.log(error.message, error.statusCode, error.body);
      if (error instanceof UnauthenticatedError) {
        console.log(error.data$.message);
      }
      if (error instanceof ResourceNotFoundError) {
        console.log("Not found:", error.data$);
      }
    }
  }
}

run();
```

### 安全方法(返回结果)

使用 `*Safe` 获取方法 `Result<T, E>` 而不是扔东西。 您可以在不尝试/抓取的情况下处理出错, 并缩小类型 :

```typescript
import {
  LambdaDBClient,
  Result,
  ResourceNotFoundError,
} from "@functional-systems/lambdadb";

const client = new LambdaDBClient({ projectApiKey: "..." });

const result = await client.listCollectionsSafe();
if (result.ok) {
  console.log(result.value.collections);
} else {
  const err = result.error;
  if (err instanceof ResourceNotFoundError) {
    console.log("Not found:", err.data$);
  } else {
    console.error(err);
  }
}
```

可用安全方法: `listCollectionsSafe`, (中文(简体) ), `createCollectionSafe`, (中文(简体) ), `collection.getSafe`, (中文(简体) ), `collection.updateSafe`, (中文(简体) ), `collection.deleteSafe`, (中文(简体) ), `collection.querySafe`, (中文(简体) ), `collection.docs.listSafe`, (中文(简体) ), `collection.docs.upsertSafe`, (中文(简体) ), `collection.docs.updateSafe`, (中文(简体) ), `collection.docs.deleteSafe`, (中文(简体) ), `collection.docs.fetchSafe`, (中文(简体) ), `collection.docs.getBulkUpsertSafe`, (中文(简体) ), `collection.docs.bulkUpsertSafe`, (中文(简体) ), `collection.docs.bulkUpsertDocsSafe`编辑 `Result` 类型和类型 `OK` 编号 : `ERR` 帮助从软件包中导出 .

数据版本生命周期控件也提供 `createSafe`, (中文(简体) ), `listSafe`, (中文(简体) ), `deleteSafe`,以及 `aliases.retargetSafe`。 。 。 .

### 错误分类

**主错误 :**

-   [`LambdaDBError`](https://npmcn.com/package/%40functional-systems/lambdadb/src/models/errors/lambdadberror.ts): HTTP 错误响应的基础类.
    -   [`UnauthenticatedError`](https://npmcn.com/package/%40functional-systems/lambdadb/src/models/errors/unauthenticatederror.ts):无正相. 状态代码 `401`。 。 。 .
    -   [`TooManyRequestsError`](https://npmcn.com/package/%40functional-systems/lambdadb/src/models/errors/toomanyrequestserror.ts): 请求过多. 状态代码 `429`。 。 。 .
    -   [`InternalServerError`](https://npmcn.com/package/%40functional-systems/lambdadb/src/models/errors/internalservererror.ts): 内部服务器出错. 状态代码 `500`。 。 。 .
    -   [`ResourceNotFoundError`](https://npmcn.com/package/%40functional-systems/lambdadb/src/models/errors/resourcenotfounderror.ts): 资源未找到 。 状态代码 `404`。 。 。 \*
    -   [`CatalogConflictError`](https://npmcn.com/package/%40functional-systems/lambdadb/src/models/errors/gatewayerrors.ts):有条件目录冲突. 状态代码 `409`。 。 。 .
    -   [`PayloadTooLargeError`](https://npmcn.com/package/%40functional-systems/lambdadb/src/models/errors/gatewayerrors.ts): 超过网关请求限制 。 状态代码 `413`。 。 。 .
    -   [`BadGatewayError`](https://npmcn.com/package/%40functional-systems/lambdadb/src/models/errors/gatewayerrors.ts):意外下游故障. 状态代码 `502`。 。 。 .
    -   [`ServiceUnavailableError`](https://npmcn.com/package/%40functional-systems/lambdadb/src/models/errors/gatewayerrors.ts): 短暂依赖失败。 状态代码 `503`。 。 。 .
    -   [`GatewayTimeoutError`](https://npmcn.com/package/%40functional-systems/lambdadb/src/models/errors/gatewayerrors.ts): 网关最后期限已超过。 状态代码 `504`。 。 。 .

少常见错误(8)  

**网络错误 :**

-   [`ConnectionError`](https://npmcn.com/package/%40functional-systems/lambdadb/src/models/errors/httpclienterrors.ts): HTTP 客户端无法向服务器提出请求.
-   [`RequestTimeoutError`](https://npmcn.com/package/%40functional-systems/lambdadb/src/models/errors/httpclienterrors.ts): HTTP 请求由于中止信号而超时.
-   [`RequestAbortedError`](https://npmcn.com/package/%40functional-systems/lambdadb/src/models/errors/httpclienterrors.ts):HTTP请求被客户端中止.
-   [`InvalidRequestError`](https://npmcn.com/package/%40functional-systems/lambdadb/src/models/errors/httpclienterrors.ts): 用于创建请求的任何输入无效.
-   [`UnexpectedClientError`](https://npmcn.com/package/%40functional-systems/lambdadb/src/models/errors/httpclienterrors.ts):无法识别或出乎意料的错误.

**继承从 [`LambdaDBError`](https://npmcn.com/package/%40functional-systems/lambdadb/src/models/errors/lambdadberror.ts)**数字 :

-   [`BadRequestError`](https://npmcn.com/package/%40functional-systems/lambdadb/src/models/errors/badrequesterror.ts):请求差. 状态代码 `400`适用于13个方法中的10个
-   [`ResourceAlreadyExistsError`](https://npmcn.com/package/%40functional-systems/lambdadb/src/models/errors/resourcealreadyexistserror.ts): 资源已经存在。 状态代码 `409`适用于13个方法中的1个
-   [`ResponseValidationError`](https://npmcn.com/package/%40functional-systems/lambdadb/src/models/errors/responsevalidationerror.ts):从服务器返回的数据和SDK期望的结构之间的类型不匹配. 见 `error.rawValue` 原值和 `error.pretty()` 用于格式化良好的多行字符串.

\* 检查 [方法文档](https://npmcn.com/package/%40functional-systems/lambdadb/#readme-available-resources-and-operations) 以查看该错误是否适用.

## 服务器选择( API 基础 URL)

`LambdaDBClient` 将 API 基础构建为 **`{baseUrl}/projects/{projectName}`**。可以在创建客户端时覆盖默认值.

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `baseUrl` | `string` | `"https://api.lambdadb.ai"` | API 基础 URL( 无跟踪斜线) . |
| `projectName` | `string` | `"playground"` | 项目名称(路径段). |
| `serverURL` | `string` | —— 说 | 全垒打 URL( 覆盖 BaseUrl + 工程Name) . |
| `projectHost` | `string` | —— 说 | 遗产:URL的主机路径(例如. `api.lambdadb.ai/projects/my-project`) (中文(简体) ). |

### 使用 BaseUrl 和工程Name (推荐)

```typescript
import { LambdaDBClient } from "@functional-systems/lambdadb";

const client = new LambdaDBClient({
  projectApiKey: "<YOUR_PROJECT_API_KEY>",
  baseUrl: "https://api.lambdadb.ai",
  projectName: "my-project",
});

const result = await client.listCollections();
```

### 覆盖完整的服务器 URL

要将基准 URL 设置在一个去, 使用 `serverURL`数字 :

```typescript
import { LambdaDBClient } from "@functional-systems/lambdadb";

const client = new LambdaDBClient({
  serverURL: "https://api.lambdadb.ai/projects/my-project",
  projectApiKey: "<YOUR_PROJECT_API_KEY>",
});

const result = await client.listCollections();
```

## 自定义 HTTP 客户端

TypeScript SDK 使用一个 `HTTPClient` 将本地人包裹起来 [获取 API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)这个 客户端是薄薄的包装 `fetch` 并且提供连接钩子的能力 围绕可用于修改请求或处理的请求生命周期 错误和反应.

这个 `HTTPClient` 构造器使用可选 `fetcher` 参数可以是 用于整合第三方 HTTP 客户端或用于编写测试以嘲弄 hTTP 客户端并输入固定设备.

以下示例说明如何使用 `"beforeRequest"` 要添加的钩子 自定义标题和请求的超时及如何使用 `"requestError"` 钩子 记录错误 :

```typescript
import { LambdaDBClient } from "@functional-systems/lambdadb";
import { HTTPClient } from "@functional-systems/lambdadb/lib/http";

const httpClient = new HTTPClient({
  // fetcher takes a function that has the same signature as native `fetch`.
  fetcher: (request) => {
    return fetch(request);
  }
});

httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request, {
    signal: request.signal || AbortSignal.timeout(5000)
  });

  nextRequest.headers.set("x-custom-header", "custom value");

  return nextRequest;
});

httpClient.addHook("requestError", (error, request) => {
  console.group("Request Error");
  console.log("Reason:", `${error}`);
  console.log("Endpoint:", `${request.method} ${request.url}`);
  console.groupEnd();
});

const client = new LambdaDBClient({ httpClient, projectApiKey: "<YOUR_PROJECT_API_KEY>" });
```

单独通过一个 `transferClient` 用于预签名上传和线外结果 下载。 API 认证和 API 唯一的信头永远不会复制到此项 运输。 待命 `signal` 财务报告和审定财务报表 `timeoutMs` 仍然适用于转移请求.

## 调试

您可以为 SDK 请求和响应设置 SDK 以发送调试日志 .

你可以通过一个匹配的日志 `console`'作为 SDK 选项的接口.

> \[尖叫声\] 注意调试日志会揭示一些秘密, 如标题中的 API 令牌, 打印到控制台或文件中的日志信息 。 建议只在本地开发期间使用这一特征,而不能用于生产.

```typescript
import { LambdaDBClient } from "@functional-systems/lambdadb";

const client = new LambdaDBClient({ debugLogger: console, projectApiKey: "<YOUR_PROJECT_API_KEY>" });
```

通过设置环境变量也可以启用默认调试日志 `LAMBDADB_DEBUG` 改为 `true` 或者说 `1` (大小写不敏感). 任何其他价值,包括 `false` 财务报告和审定财务报表 `0`,让它残废.

# 发展

## 成熟度

这个SDK是在β中,在版本之间可能会有断裂的更改,而没有主要的版本更新. 因此,我们建议把使用定在特定的软件包版本,除非你有意寻找最新的版本.

## 捐款

我们欢迎各方的贡献。 推荐的API在 `src/client.ts` (LambdaDBClient,收集范围. 其余部分 `src/` (funcs, models, lib) 手动维护; 见 [文件/OPENAPI UPD.md](https://npmcn.com/package/%40functional-systems/lambdadb/docs/OPENAPI_UPDATE.md) 用于应用 API 更改。 随便开个公关或者问题.

## 常见问题

### @functional-systems/lambdadb 是什么？

开发者友好型和型号安全型 SDK 专门适应杠杆 蓝巴达德布 API \(英语\)\.

### 如何安装 @functional-systems/lambdadb？

在项目目录运行 npm install @functional-systems/lambdadb，或使用 pnpm add / yarn add / bun add。

### @functional-systems/lambdadb 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @functional-systems/lambdadb 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @functional-systems/lambdadb 可以商用吗？

@functional-systems/lambdadb 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @functional-systems/lambdadb 的下载量有多少？

根据 npm 官方下载统计，@functional-systems/lambdadb 在 2026/10/16 – 2026/11/14 这 30 天内被下载 5,820 次，日均约 194 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @functional-systems/lambdadb 还在维护吗？

最新版本 0\.12\.0 发布于 2026/11/06（9 天前）；至今共发布 59 个版本，其中过去 12 个月发布了 56 个；首次发布于 2025/08/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。