Convex地理空间指数(Beta)
此组件为 Convex 添加了地理空间索引, 允许您高效 在地球表面存储和查询点.
- 在地理空间关键值库中插入点及其地理 坐标.
- 高效查询球体上指定矩形内的所有点 .
- 用自定义排序键控制结果的排序顺序 .
- 以平等方式过滤查询结果
IN条款. - 既然它建在Convex上 一切都自动一致, 反应,缓存!
此成分目前为β. 它缺少一些功能,但是什么 应该有用 我们测试过这个应用 大约100万分,所以 如果使用更大的数据集,请联系。 如果你找到一个错误或有一个 特性请求,你可以 在这里归档。 。 。 .
预先要求: Convex
你需要一个现有的 Convex 项目来使用组件。 Convex 是一个主机 后端平台,包括数据库、无服务器功能和多一个吨 可以学习 这里。 。 。 .
运行 npm create convex 或遵循其中任何一条
快速启动 来设置一个.
安装
第一,添加 @convex-dev/geospatial 到您的 Convex 项目 :
npm install @convex-dev/geospatial
然后,将组件安装到您的 Convex 工程中
convex/convex.config.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/ 文件夹和点
至已安装组件:
// 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。 。 。 .
// 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 将在另一个表格中显示
属于你的.
// 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 (英语).
// 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() 过滤器,需要
匹配文档有一个过滤字段,在指定的一组中有值.
// 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() 过滤器,需要
匹配文档有一个过滤字段,其值等于指定的值.
// 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我们目前只支持(可选的)包容性的下限和
独有上界.
// 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 参数.
// 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 从正在开始的客户端中插入
通过结果,避免在单个查询中载入过多的数据.
查询最接近的查询点
您也可以查询最接近给定点的点,可选择限制 最大距离(以米计).
// 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 进一步限制搜索空间,并能大大加快搜索速度
查找索引 .
示例
发展
安装依赖性并点火示例应用程序以启动 .
npm install
cd example
npm install
npm run dev
构成部分定义为: src/ 并反映构成部分的哪些用户
将安装。 这个完全独立的例子应用程序生活在
example/。 。 。 .