Typesense 中 GeoSearch 查询的排序语法问题解析

问题背景

在使用 Typesense 进行地理位置搜索时，开发者经常会遇到 Bad syntax for sorting field 的错误提示。这个问题通常出现在尝试对嵌套的地理坐标字段进行排序时，特别是当这些字段位于对象结构中时。

错误原因分析

通过一个实际案例我们可以看到，开发者尝试对 address.coords 这个嵌套字段进行地理位置排序时遇到了语法错误。原始的错误查询如下：

{
  "collection": "communities_development",
  "q": "Ru",
  "query_by": "name",
  "sort_by": "address.coords(48.853, 2.344):asc"
}

错误的核心在于 schema 定义方式不正确。开发者最初尝试使用嵌套对象的方式来定义 schema：

{
  name: 'address',
  type: 'object',
  fields: [
    { name: 'street', type: 'string', optional: true, sort: true },
    {
      name: 'coords',
      type: 'geopoint',
      sort: true,
    },
  ],
}

这种定义方式在 Typesense 中是不支持的，因为 fields 属性只能在顶级 schema 定义中使用，不能在嵌套对象中使用。

正确的解决方案

正确的做法是将嵌套字段扁平化处理，使用点号表示法来定义嵌套字段：

{
  name: 'communities',
  enable_nested_fields: true,
  fields: [
    { name: 'name', type: 'string' },
    { name: 'privacy', type: 'string', facet: true },
    { name: 'type', type: 'string', facet: true },
    { name: 'description', type: 'string' },
    { name: 'created_at', type: 'int64' },
    { name: 'address.street', type: 'string', optional: true, sort: true },
    { name: 'address.coords', type: 'geopoint' }
  ],
}

技术要点总结

1. Schema 定义规则：Typesense 不支持在嵌套对象中使用 fields 属性，所有字段定义必须在顶级 schema 中完成。

2. 嵌套字段表示法：对于嵌套字段，应该使用点号表示法（如 address.coords）而不是对象嵌套的方式。

3. 地理位置排序：当使用 geopoint 类型字段进行排序时，确保字段定义正确且排序语法格式正确。

4. 错误排查：当遇到排序语法错误时，首先检查 schema 定义是否符合规范，然后再检查查询语法。

最佳实践建议

1. 在设计 schema 时，优先考虑使用扁平化的字段结构，特别是对于需要排序或过滤的字段。

2. 对于地理位置搜索，确保 geopoint 类型的字段定义正确，并且索引已正确创建。

3. 在开发过程中，可以先使用简单的查询测试基本功能，再逐步添加复杂的排序和过滤条件。

4. 充分利用 Typesense 的错误提示信息，它们通常能准确指出问题所在。

通过遵循这些原则，开发者可以避免类似的地理位置排序语法错误，构建出更稳定高效的搜索功能。