# @convex-dev/geospatial 中文文档

规范地址：https://npmcn.com/package/%40convex-dev/geospatial/

版本：0\.2\.1
npm 元数据更新时间：2026-10-07T00:51:42.018Z
中文译文更新时间：2026-11-10T17:49:56.512Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：1.3 MB，167 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：convex ^1\.24\.8
- 首次发布：2024-10-16T00:28:08.263Z
- 最新版本发布：2025-12-11T00:48:37.684Z
- 近 30 天下载量：110850（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 2 个）

## 中文简介

Convex 地理空间索引

## 安装

```sh
npm install @convex-dev/geospatial
```

也可以使用：`pnpm add @convex-dev/geospatial`、`yarn add @convex-dev/geospatial`、`bun add @convex-dev/geospatial`

## README

# Convex地理空间指数(Beta)

[![npm version](https://badge.fury.io/js/@convex-dev%2Fgeospatial.svg)](https://badge.fury.io/js/@convex-dev%2Fgeospatial)

![image](https://frugal-mandrill-176.convex.cloud/api/storage/8fb21c7f-441c-4ce9-9abb-925c31e9faab)

此组件为 Convex 添加了地理空间索引, 允许您高效 在地球表面存储和查询点.

-   在地理空间关键值库中插入点及其地理 坐标.
-   高效查询球体上指定矩形内的所有点 .
-   用自定义排序键控制结果的排序顺序 .
-   以平等方式过滤查询结果 `IN` 条款.
-   既然它建在Convex上 一切都自动一致, 反应,缓存!

此成分目前为β. 它缺少一些功能,但是什么 应该有用 我们测试过这个应用 大约100万分,所以 如果使用更大的数据集,请联系。 如果你找到一个错误或有一个 特性请求,你可以 [在这里归档](https://github.com/get-convex/geospatial/issues)。 。 。 .

## 预先要求: Convex

你需要一个现有的 Convex 项目来使用组件。 Convex 是一个主机 后端平台,包括数据库、无服务器功能和多一个吨 可以学习 [这里](https://docs.convex.dev/get-started)。 。 。 .

运行 `npm create convex` 或遵循其中任何一条 [快速启动](https://docs.convex.dev/home) 来设置一个.

## 安装

第一,添加 `@convex-dev/geospatial` 到您的 Convex 项目 :

```bash
npm install @convex-dev/geospatial
```

然后,将组件安装到您的 Convex 工程中 `convex/convex.config.ts` 文件 :

```ts
// convex/convex.config.ts
import geospatial from "@convex-dev/geospatial/convex.config.js";
import { defineApp } from "convex/server";

const app = defineApp();
app.use(geospatial);

export default app;
```

最后,创建一个新的 `GeospatialIndex` 在您内部 `convex/` 文件夹和点 至已安装组件:

```ts
// convex/index.ts
import { GeospatialIndex } from "@convex-dev/geospatial";
import { components } from "./_generated/api";

const geospatial = new GeospatialIndex(components.geospatial);
```

## 插入点

安装组件后,您可以 `insert`, (中文(简体) ), `get`,以及 `remove` 点 从索引。 您可以指定一个 `filterKeys` 查询时过滤的记录 时间和可选a `sortKey` 用于查询结果顺序。 现在只有我们 支持在 `sortKey`。 。 。 .

```ts
// convex/index.ts

const example = mutation({
  handler: async (ctx) => {
    const cityId = await ctx.db.insert("cities", {...});
    await geospatial.insert(
      ctx,
      "American Museum of Natural History",
      {
        latitude: 40.7813,
        longitude: -73.9737,
      },
      { category: "museum" },
      28.0, // Price used as the sort key
    );
    const result = await geospatial.get(ctx, cityId);
    await geospatial.remove(ctx, cityId);
  },
});
```

如果您想要更多类型安全, 您可以指定类型参数 `GeospatialIndex` 课。 这也会为您提供自动完成 `filterKeys` 财务报告和审定财务报表 `sortKey` 参数。 关键是美国博物馆 自然历史,但最常见的是 `key` 将在另一个表格中显示 属于你的.

```ts
// convex/index.ts
import { GeospatialIndex, Point } from "@convex-dev/geospatial";
import { components } from "./_generated/api";
import { Id } from "./_generated/dataModel";

export const geospatial = new GeospatialIndex<
  Id<"museums">,
  { category: string; anotherFilter?: number }
>(components.geospatial);
```

## 在形状中查询点

插入一些点后,您可以使用 `query` API (英语).

```ts
// convex/index.ts

const example = query({
  handler: async (ctx) => {
    const rectangle = {
      west: -73.9712,
      south: 40.7831,
      east: -72.9712,
      north: 41.7831,
    };
    const result = await geospatial.query(ctx, {
      shape: { type: "rectangle", rectangle },
      limit: 16,
    });
    return result;
  },
});
```

遗产 `queryNearest` 帮助现在的代表 `nearest` 并堕地而去. 它只接受一个 `maxDistance` 反向兼容性的数字参数. 新的一体化应更可取 `nearest`。 。 。 .

此查询将找到查询矩形内的所有点, 并排序它们 上升时 `sortKey` 命令,最多返回16个结果.

您可以在查询中选择添加过滤条件.

第一类过滤条件为 `in()` 过滤器,需要 匹配文档有一个过滤字段,在指定的一组中有值.

```ts
// convex/index.ts

const example = query({
  handler: async (ctx) => {
    const rectangle = {
      west: -73.9712,
      south: 40.7831,
      east: -72.9712,
      north: 41.7831,
    };
    const result = await geospatial.query(ctx, {
      shape: { type: "rectangle", rectangle },
      filter: (q) => q.in("category", ["museum", "restaurant"]),
    });
    return result;
  },
});
```

第二类过滤条件为 `eq()` 过滤器,需要 匹配文档有一个过滤字段,其值等于指定的值.

```ts
// convex/index.ts

const example = query({
  handler: async (ctx) => {
    const result = await geospatial.query(ctx, {
      shape: { type: "rectangle", rectangle },
      filter: (q) => q.eq("category", "museum"),
    });
    return result;
  },
});
```

最后类型的过滤条件允许您在 `sortKey`我们目前只支持(可选的)包容性的下限和 独有上界.

```ts
// convex/index.ts

const example = query({
  handler: async (ctx) => {
    const rectangle = {
      west: -73.9712,
      south: 40.7831,
      east: -72.9712,
      north: 41.7831,
    };
    const result = await geospatial.query(ctx, {
      shape: { type: "rectangle", rectangle },
      filter: (q) => q.gte("sortKey", 10).lt("sortKey", 30),
    });
    return result;
  },
});
```

查询录入a `limit`,它约束了返回的最大行数。 若为 此限制被击中, 查询将返回 a `nextCursor` 继续 这个 查询也可能返回 a `nextCursor` 少于 `limit` 如果运行结果 从其执行时的IO预算中扣除.

无论是哪种情况,你都可以通过路过继续流水 `nextCursor` 到下一个 电话 `cursor` 参数.

```ts
// convex/index.ts

const example = query({
  handler: async (ctx) => {
    const rectangle = {
      west: -73.9712,
      south: 40.7831,
      east: -72.9712,
      north: 41.7831,
    };
    const startCursor = undefined;
    const result = await geospatial.query(
      ctx,
      {
        shape: { type: "rectangle", rectangle },
        limit: 16,
      },
      startCursor,
    );
    if (result.nextCursor) {
      // Continue the query, starting from the first query's cursor.
      const nextResult = await geospatial.query(
        ctx,
        {
          shape: { type: "rectangle", rectangle },
          limit: 16,
        },
        result.nextCursor,
      );
      return [...result.results, ...nextResult.results];
    }
    return result.results; // { key, coordinates }[]
  },
});
```

**注意:您通常通过 `nextCursor` 从正在开始的客户端中插入 通过结果,避免在单个查询中载入过多的数据.**

## 查询最接近的查询点

您也可以查询最接近给定点的点,可选择限制 最大距离(以米计).

```ts
// convex/index.ts

const example = query({
  handler: async (ctx) => {
    const maxResults = 16;
    const maxDistance = 10000;
    const result = await geospatial.nearest(ctx, {
      point: { latitude: 40.7813, longitude: -73.9737 },
      limit: maxResults,
      maxDistance,
      filter: (q) => q.eq("category", "coffee"),
    });
    return result;
  },
});
```

第二个参数是一个包含 `point`, (中文(简体) ), `limit`,以及 可选择 `maxDistance` 财务报告和审定财务报表 `filter`组合 `maxDistance` 与 相同的过滤器构建器 `query`,包括: `eq`, (中文(简体) ), `in`, (中文(简体) ), `gte`,以及 `lt` 条件。 这些过滤器通过索引执行 `pointsByFilterKey` 范围在文档被装入之前,所以数据库进行起重和 查询避免读取无关的点。 和理智对等 `maxDistance` 进一步限制搜索空间,并能大大加快搜索速度 查找索引 .

## 示例

见 [`example/`](https://npmcn.com/package/%40convex-dev/geospatial/example/) 一个完整的例子 [传单](https://leafletjs.com/)\- 总部前端.

## 发展

安装依赖性并点火示例应用程序以启动 .

```bash
npm install
cd example
npm install
npm run dev
```

构成部分定义为: `src/` 并反映构成部分的哪些用户 将安装。 这个完全独立的例子应用程序生活在 `example/`。 。 。 .

## 常见问题

### @convex-dev/geospatial 是什么？

Convex 地理空间索引

### 如何安装 @convex-dev/geospatial？

在项目目录运行 npm install @convex-dev/geospatial，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：convex（^1\.24\.8）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @convex-dev/geospatial 支持 TypeScript 吗？

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

### @convex-dev/geospatial 支持 ESM 还是 CommonJS？

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

### @convex-dev/geospatial 可以商用吗？

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

### @convex-dev/geospatial 的下载量有多少？

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

### @convex-dev/geospatial 还在维护吗？

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