# @cereusdb/standard 中文文档

规范地址：https://npmcn.com/package/%40cereusdb/standard/

版本：0\.4\.0
npm 元数据更新时间：2026-10-06T11:05:31.500Z
中文译文更新时间：2026-11-09T08:07:19.797Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40cereusdb/standard
原文对照：https://npmcn.com/package/%40cereusdb/standard/?lang=original
项目主页：https://github.com/tobilg/cereusdb#readme
源码仓库：https://github.com/tobilg/cereusdb

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

- 包体积（解压后）：30.4 MB，16 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：0 个
- 首次发布：2026-04-11T09:24:20.833Z
- 最新版本发布：2026-10-06T11:05:31.108Z
- 近 30 天下载量：6635（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

标准 CeeusDB 浏览器包, 并附有 GEOS 和 PROJ 支持

## 安装

```sh
npm install @cereusdb/standard
```

也可以使用：`pnpm add @cereusdb/standard`、`yarn add @cereusdb/standard`、`bun add @cereusdb/standard`

## README

# @cereusdb/标准

标准 CereusDB 浏览器包. 里面的东西 `@cereusdb/minimal`,加上PROJ支持 `ST_Transform` 和CRS-意识再预测支持.

此软件包包括用于远程 Parquet 读取的浏览器对象商店和S3/GCS/Azure/HTTP提供商.

## 安装

```bash
npm install @cereusdb/standard
```

## 公园支持

用 Snappy, Gzip, Brotli, LZ4 或 ZSTD 压缩的 Parquet 文件可以注册.

## SQL 函数可用性

当前运行时间表面 :

-   `151` 运行时间 `ST_*` 名称
-   `0` 运行时间 `RS_*` 名称

包含函数家族 :

-   一切从 `@cereusdb/minimal`: 核心SedonaDB函数, `geo` 函数、对地观测分布式上游/操作、关系连接、距离连接,以及 `ST_KNN`。 。 。 .
-   PROJ 支持的 CRS 转换 `ST_Transform`。 。 。 .

现有功能的例子:

-   核心预算和 `geo`数字 : `ST_Point`, (中文(简体) ), `ST_GeomFromWKT`, (中文(简体) ), `ST_AsText`, (中文(简体) ), `ST_SRID`, (中文(简体) ), `ST_Buffer`, (中文(简体) ), `ST_Distance`, (中文(简体) ), `ST_DWithin`, (中文(简体) ), `ST_AsGeoJSON`
-   乔治: `ST_Contains`, (中文(简体) ), `ST_Within`, (中文(简体) ), `ST_Crosses`, (中文(简体) ), `ST_Touches`, (中文(简体) ), `ST_Union`, (中文(简体) ), `ST_Difference`, (中文(简体) ), `ST_MakeValid`, (中文(简体) ), `ST_Polygonize`
-   普罗杰: `ST_Transform`

本套件中没有包含 :

-   S2 地理内核
-   鼠标 `RS_*` 函数

## 对象存储支持

浏览器对象存储包含在 `@cereusdb/standard`启用 `registerObjectStores()` 要配置 `http`, (中文(简体) ), `s3`, (中文(简体) ), `gcs`,或 `azure` 提供商,那么 `registerParquetTable()` 以注册精确的 Parquet 对象或提供者支持的前缀.

## 持久性数据库(OPFS)

表格通常生活在记忆中。 持久性数据库被存储在浏览器的"起源"(Origin Private File System)中并活下来的页面重载:

```ts
const db = await CereusDB.create({ attach: ['opfs://mydb'] }); // opens or creates mydb

await db.sqlJSON(`CREATE TABLE mydb.public.cities AS SELECT 1 AS id, 'Berlin' AS name, ST_Point(13.4, 52.5) AS geom`);
await db.sqlJSON(`INSERT INTO mydb.public.cities VALUES (2, 'Paris', ST_Point(2.35, 48.86))`);
await db.sqlJSON(`USE mydb`); // `cities` now resolves to mydb.public.cities
```

SQL : (英语) `CREATE DATABASE 'opfs://mydb'`, (中文(简体) ), `ATTACH 'opfs://mydb' [AS name]`, (中文(简体) ), `DETACH name`, (中文(简体) ), `DROP DATABASE name`, (中文(简体) ), `USE name`, (中文(简体) ), `ALTER TABLE ... RENAME TO | ADD COLUMN | DROP COLUMN | RENAME COLUMN`,以及 `SELECT * FROM cereusdb_databases()`数据库作为目录出现在 `information_schema` 财务报告和审定财务报表 `db.catalog()`。表格中的数据在首次使用时被载入。 见 [持久性数据库指南](https://github.com/tobilg/cereusdb/blob/main/packages/documentation/guides/persistent-databases.md)。 。 。 .

## GeoParquet 导出

```ts
const bytes = await db.exportGeoParquet('mydb.public.cities'); // Uint8Array
await db.downloadGeoParquet('mydb.public.cities');            // downloads cities.parquet
await db.sqlJSON(`COPY (SELECT * FROM cities WHERE id > 1) TO 'some.parquet'`);
```

见 [GeoParquet 导出指南](https://github.com/tobilg/cereusdb/blob/main/packages/documentation/guides/geoparquet-export.md)。 。 。 .

## 装入 WASM 模块

本来是二进制的船作为单独的档案, `dist/wasm/cereusdb_bg.wasm`。默认条目自动查找,捆绑者将其作为资产放出.

如果你主机是你自己,或者你的捆绑者 将资产注入大 `data:application/wasm;base64,...` 字符串,使用 `external` 输入。 它没有内置的 参考和需要 `wasmUrl` 或者说 `wasmSource`数字 :

```ts
import { CereusDB } from '@cereusdb/standard/external';

const db = await CereusDB.create({ wasmUrl: '/wasm/cereusdb_bg.wasm' });
```

复制 `node_modules/@cereusdb/standard/dist/wasm/cereusdb_bg.wasm` 到您的静态资产,或用 Vite 导入其 URL : `import wasmUrl from '@cereusdb/standard/wasm?url'`见 [WASM 装载指南](https://github.com/tobilg/cereusdb/blob/main/packages/documentation/guides/wasm-loading.md) 详细情况.

## JS/TS API 联合材料

输出 :

-   `CereusDB`
-   `CereusDBOptions`
-   `ObjectStoreRegistryConfig`
-   `ObjectStoreConfig`
-   `ObjectStoreProvider`
-   `RegisterParquetTableOptions`
-   `RasterFormat`
-   `QueryResult`
-   `MemoryStorageBackend`, (中文(简体) ), `OPFSStorageBackend`, (中文(简体) ), `StorageBackend`, (中文(简体) ), `StorageOptions`
-   `CreateDatabaseOptions`, (中文(简体) ), `AttachDatabaseOptions`, (中文(简体) ), `DatabaseListing`
-   `CatalogDatabase`, (中文(简体) ), `CatalogSchema`, (中文(简体) ), `CatalogTable`, (中文(简体) ), `CatalogColumn`
-   `CreateTableDefinition`, (中文(简体) ), `CreateTableOptions`, (中文(简体) ), `AlterTableOperation`
-   `GeoParquetExportOptions`, (中文(简体) ), `DownloadGeoParquetOptions`, (中文(简体) ), `ExportHandler`
-   `downloadFile`, (中文(简体) ), `PARQUET_MIME_TYPE`

主要类型 :

```ts
interface StorageOptions {
  opfs?: StorageBackend | false; // default: OPFSStorageBackend when the browser has OPFS
  [scheme: string]: StorageBackend | false | undefined;
}

interface StorageBackend {
  readFile(path: string): Promise<Uint8Array | null>;
  writeFile(path: string, data: Uint8Array): Promise<void>;
  remove(path: string): Promise<void>;
  list(path: string): Promise<string[]>;
  lock?(name: string): Promise<void>;
  unlock?(name: string): Promise<void>;
}

type ExportHandler = (filename: string, data: Uint8Array, mimeType: string) => void | Promise<void>;

type CreateTableDefinition = { columns: Record<string, string> } | { as: string };

type AlterTableOperation =
  | { renameTo: string }
  | { addColumn: { name: string; type: string; notNull?: boolean; default?: string }; ifNotExists?: boolean }
  | { dropColumn: string | string[]; ifExists?: boolean }
  | { renameColumn: { from: string; to: string } };

interface GeoParquetExportOptions {
  compression?: 'zstd' | 'snappy' | 'lz4' | 'gzip' | 'brotli' | 'uncompressed';
  rowGroupSize?: number;
}

interface DownloadGeoParquetOptions extends GeoParquetExportOptions {
  filename?: string;
}

type RasterFormat = 'geotiff' | 'tiff';
type ObjectStoreProvider = 'http' | 's3' | 'gcs' | 'azure';

interface CereusDBOptions {
  wasmUrl?: string;
  wasmSource?:
    | RequestInfo
    | URL
    | Response
    | BufferSource
    | WebAssembly.Module
    | Promise<Response>;
  objectStores?: ObjectStoreRegistryConfig;
  storage?: StorageOptions;
  attach?: string[];
  onExport?: ExportHandler | false;
}

interface ObjectStoreRegistryConfig {
  maxConcurrency?: number;
  stores: ObjectStoreConfig[];
}

interface ObjectStoreConfig {
  name?: string;
  provider: ObjectStoreProvider;
  url: string;
  options?: Record<string, string | number | boolean>;
}

interface RegisterParquetTableOptions {
  fileExtension?: string;
  targetPartitions?: number;
}
```

主 API :

```ts
class CereusDB {
  static create(options?: CereusDBOptions): Promise<CereusDB>;
  sql(query: string): Promise<Uint8Array>;
  sqlJSON(query: string): Promise<Record<string, unknown>[]>;
  registerRemoteParquet(name: string, url: string): Promise<void>;
  registerObjectStores(config: ObjectStoreRegistryConfig): void;
  registerParquetTable(
    name: string,
    url: string,
    options?: RegisterParquetTableOptions,
  ): Promise<void>;
  registerFile(name: string, file: File): Promise<void>;
  registerGeoJSON(name: string, geojson: string | object): void;
  registerRaster(name: string, data: BufferSource, format: RasterFormat): void;
  registerGeoTIFF(name: string, data: BufferSource): void;
  dropTable(name: string): Promise<void>;
  catalog(): Promise<CatalogDatabase[]>;
  createDatabase(location: string, options?: CreateDatabaseOptions): Promise<string>;
  attachDatabase(location: string, options?: AttachDatabaseOptions): Promise<string>;
  detachDatabase(name: string, options?: { ifExists?: boolean }): Promise<void>;
  dropDatabase(nameOrLocation: string, options?: { ifExists?: boolean }): Promise<void>;
  useDatabase(database: string, schema?: string): Promise<void>;
  listDatabases(): Promise<DatabaseListing[]>;
  createTable(name: string, definition: CreateTableDefinition, options?: CreateTableOptions): Promise<void>;
  alterTable(name: string, operation: AlterTableOperation): Promise<void>;
  insertArrow(table: string, data: BufferSource): Promise<number>;
  compactDatabase(name: string): Promise<void>;
  flush(): Promise<void>;
  exportGeoParquet(queryOrTable: string, options?: GeoParquetExportOptions): Promise<Uint8Array>;
  downloadGeoParquet(queryOrTable: string, options?: DownloadGeoParquetOptions): Promise<string>;
  tables(options?: { qualified?: boolean }): string[];
  version(): string;
}
```

API 注释 :

-   `sql()` 返回箭头 IPC 字节为 `Uint8Array`。 。 。 .
-   `sqlJSON()` 返回已解析的 JSON 行.
-   `registerFile()` 支持 `.parquet`, (中文(简体) ), `.geoparquet`, (中文(简体) ), `.geojson`,以及 `.json` 本包中.
-   `registerObjectStores()` 财务报告和审定财务报表 `registerParquetTable()` 支持浏览器后置范围 Parquet 读取 `http`, (中文(简体) ), `s3`, (中文(简体) ), `gcs`,以及 `azure` 供养者.
-   S3 临时全权证书的使用 `access_key_id`, (中文(简体) ), `secret_access_key`,以及 `token`时 `token` 是STS吗 `SessionToken`。 。 。 .
-   S3相容端点可以配置为 `endpoint`; 使用 `allow_http: true` 用于本地的 HTTP 端点,例如 MinIO 或 LocalStack .
-   `registerRaster()` 财务报告和审定财务报表 `registerGeoTIFF()` 属于共享包装,但光栅注册要求 `@cereusdb/full`。 。 。 .
-   持续数据库`createDatabase()` 和相关的方法), `ALTER TABLE`, (中文(简体) ), `insertArrow()`, (中文(简体) ), `catalog()` 和 GeoParquet 导出于每个软件包.
-   `downloadGeoParquet()` 财务报告和审定财务报表 `COPY ... TO` 将文件传递到 `onExport` 处理器:主线程默认的浏览器下载;在Web Workers或Node.js中通过自己的处理器.

## 示例

```ts
import { CereusDB } from '@cereusdb/standard';

const db = await CereusDB.create();

const rows = await db.sqlJSON(`
  SELECT ST_AsText(
    ST_Transform(
      ST_GeomFromWKT('POINT(13.4 52.5)'),
      'EPSG:4326',
      'EPSG:3857'
    )
  ) AS geom
`);

console.log(rows);
```

## 常见问题

### @cereusdb/standard 是什么？

标准 CeeusDB 浏览器包, 并附有 GEOS 和 PROJ 支持

### 如何安装 @cereusdb/standard？

在项目目录运行 npm install @cereusdb/standard，或使用 pnpm add / yarn add / bun add。

### @cereusdb/standard 支持 TypeScript 吗？

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

### @cereusdb/standard 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cereusdb/standard 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cereusdb/standard 可以商用吗？

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

### @cereusdb/standard 的下载量有多少？

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

### @cereusdb/standard 还在维护吗？

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