空间值

Cypher^® 内置支持处理空间值 (POINT 值)，这些值可以作为属性存储在 Neo4j 数据库的节点和关系上。

本节首先解释了 POINT 类型。然后讨论了 Cypher 对坐标参考系统（Coordinate Reference Systems）的支持，以及如何在 Cypher 中使用空间瞬时值，包括空间点瞬时值如何与 Cypher 索引配合使用。最后，简要解释了空间瞬时值的可比性和可排序性。

有关空间函数的更多信息（允许创建和操作空间值），请参阅空间函数部分。

有关空间值比较和排序的更多信息，请参阅空间值和时间值排序部分。

POINT 类型

Neo4j 支持用于空间几何值的 POINT 类型。

具有 POINT 类型的值具有以下特征

每个点可以有 2 或 3 个维度。这意味着它包含 2 或 3 个 64 位 FLOAT 值，这些值共同称为*坐标*。
每个点还将与一个特定的坐标参考系统 (CRS) 相关联，该系统决定了*坐标*中值的含义。
POINT 和 LIST<POINT> 的实例可以分配给节点和关系属性。
具有 POINT 或 LIST<POINT> 属性的节点和关系可以使用点索引进行索引。这适用于所有 CRS（以及 2D 和 3D）。
距离函数将适用于所有 CRS 中的 2D 和 3D 点，但前提是两个点具有相同的 CRS（因此也具有相同的维度）。

坐标参考系统

支持四种坐标参考系统（CRS），每种都属于两种类型之一：*地理坐标*（用于建模地球上的点）或*笛卡尔坐标*（用于建模欧几里得空间中的点）

不同坐标系统中的数据完全不可比较，也无法隐式地相互转换。即使它们都是笛卡尔坐标系或地理坐标系但维度不同，也是如此。例如，如果您使用 2D 范围搜索 3D 点，将不会得到任何结果。但是，它们可以排序，具体内容在空间值和时间值排序部分有更详细的讨论。

地理坐标参考系统

支持两种地理坐标参考系统（CRS），用于建模地球上的点

WGS 84 2D
- 在 WGS 84 CRS 中，2D 地理点可以通过以下两种方式之一指定
  - longitude 和 latitude（如果指定了这些参数，而未指定 crs，则 crs 默认为 WGS-84）。
  - x 和 y（在这种情况下必须指定 crs，否则将假定为笛卡尔坐标系）。
- 可以使用名称 'wgs-84' 或 SRID 4326 来指定此 CRS，如point() - WGS 84 2D中所述。
WGS 84 3D
- 在 WGS 84 CRS 中，3D 地理点可以通过以下两种方式之一指定
  - longitude、latitude 以及 height 或 z（如果指定了这些参数，而未指定 crs，则 crs 默认为 WGS-84-3D）。
  - x、y 和 z（在这种情况下必须指定 crs，否则将假定为 Cartesian-3D）。
- 可以使用名称 'wgs-84-3d' 或 SRID 4979 来指定此 CRS，如point() - WGS 84 3D中所述。

转换坐标单位

latitude 和 longitude 字段的单位是十进制度，需要使用 Cypher 字面量指定为浮点数。不支持使用任何其他格式，例如“度、分、秒”。height 字段的单位是米。当地理点传递给距离函数时，结果将始终以米为单位。如果坐标的格式或单位与支持的不同，则需要显式转换。

例如，如果传入的 $height 是一个以千米为单位的 STRING 字段，则需要在查询中添加 height: toFloat($height) * 1000。同样，如果 distance 函数的结果预期以千米为单位返回，则需要进行显式转换。下面的查询是此转换的一个示例

查询

WITH
  point({latitude: toFloat('13.43'), longitude: toFloat('56.21')}) AS p1,
  point({latitude: toFloat('13.10'), longitude: toFloat('56.41')}) AS p2
RETURN toInteger(point.distance(p1, p2)/1000) AS km

表 1. 结果
千米
`42`
行数：1

笛卡尔坐标参考系统

支持两种笛卡尔坐标参考系统（CRS），用于建模欧几里得空间中的点

笛卡尔 2D
- 在 笛卡尔 CRS 中，2D 点通过包含 x 和 y 坐标值的映射来指定
- 可以使用名称 'cartesian' 或 SRID 7203 来指定此 CRS，如point() - 笛卡尔 2D中所述
笛卡尔 3D
- 在 笛卡尔 CRS 中，3D 点通过包含 x、y 和 z 坐标值的映射来指定
- 可以使用名称 'cartesian-3d' 或 SRID 9157 来指定此 CRS，如point() - 笛卡尔 3D)中所述

x、y 和 z 字段的单位未指定。这意味着当两个笛卡尔点传递给 distance 函数时，结果值将与原始坐标的单位相同。这对于 2D 和 3D 点都适用，因为所使用的*勾股定理*方程可以推广到任意维数。但是，就像您不能将地理点与笛卡尔点进行比较一样，您也不能计算 2D 点和 3D 点之间的距离。如果需要这样做，请显式将一种类型转换为另一种类型。例如

查询

WITH
  point({x: 3, y: 0}) AS p2d,
  point({x: 0, y: 4, z: 1}) AS p3d
RETURN
  point.distance(p2d, p3d) AS bad,
  point.distance(p2d, point({x: p3d.x, y: p3d.y})) AS good

表 2. 结果
错误	正确
`<null>`	`5.0`
行数：1

空间瞬时值

所有 POINT 类型都由两个组件创建

*坐标*，包含 2 或 3 个 64 位 FLOAT 值。
坐标参考系统（或 CRS），定义*坐标*中值的含义（以及可能的单位）。

对于大多数用例，无需显式指定 CRS，因为它将从用于指定坐标的键中推导出来。根据坐标推导 CRS 时会应用两条规则

键的选择
- 如果使用 latitude 和 longitude 键指定坐标，则 CRS 将被假定为*地理坐标系*，因此是 WGS-84 或 WGS-84-3D。
- 如果改为使用 x 和 y，则默认 CRS 将是 Cartesian 或 Cartesian-3D。
维度数量
- 如果坐标中有 2 个维度，即 x 和 y 或 longitude 和 latitude，则 CRS 将是 2D CRS。
- 如果坐标中有第三个维度，即 z 或 height，则 CRS 将是 3D CRS。

所有字段都以显式命名参数映射的形式提供给 point 函数。Neo4j 不支持坐标字段的有序列表，因为地理坐标和笛卡尔坐标之间存在相互矛盾的约定，其中地理坐标通常将 y 列在 x 之前（latitude 列在 longitude 之前）。

以下查询返回在四种支持的 CRS 中创建的点。请特别注意原始 point 函数中坐标的顺序和键，以及这些值在结果中如何显示

查询

RETURN
  point({x: 3, y: 0}) AS cartesian_2d,
  point({x: 0, y: 4, z: 1}) AS cartesian_3d,
  point({latitude: 12, longitude: 56}) AS geo_2d,
  point({latitude: 12, longitude: 56, height: 1000}) AS geo_3d

表 3. 结果
cartesian_2d	cartesian_3d	geo_2d	geo_3d
`point({srid:7203, x: 3.0, y: 0.0})`	`point({srid:9157, x: 0.0, y: 4.0, z: 1.0})`	`point({srid:4326, x: 56.0, y: 12.0})`	`point({rid:4979, x: 56.0, y: 12.0, z: 1000.0})`
行数：1

对于地理坐标，请务必注意 latitude 值应始终位于 [-90, 90] 区间内。超出此范围的任何其他值都将抛出异常。longitude 值应始终位于 [-180, 180] 区间内。超出此范围的任何其他值都将被环绕以适应此范围。height 值和任何笛卡尔坐标没有明确的限制。64 位有符号浮点类型允许范围内的任何值都将被接受。

点的组件

POINT 值的组件可以作为属性访问。

表 4. `POINT` 实例的组件及其支持位置
组件	描述	类型	范围/格式
`instant.x`	坐标的第一个元素	`FLOAT`	数字字面量，范围取决于 CRS
`instant.y`	坐标的第二个元素	`FLOAT`	数字字面量，范围取决于 CRS
`instant.z`	坐标的第三个元素	`FLOAT`	数字字面量，范围取决于 CRS
`instant.longitude`	地理 CRS 坐标的第一个元素，本初子午线以东的度数	`FLOAT`	数字字面量，`-180.0` 到 `180.0`
`instant.latitude`	地理 CRS 坐标的第二个元素，赤道以北的度数	`FLOAT`	数字字面量，`-90.0` 到 `90.0`
`instant.height`	地理 CRS 坐标的第三个元素，高于基准面（WGS-84）定义的椭球体的米数	`FLOAT`	数字字面量，范围仅受底层 64 位浮点类型限制
`instant.crs`	CRS 的名称	`STRING`	`wgs-84`、`wgs-84-3d`、`cartesian`、`cartesian-3d` 之一
`instant.srid`	CRS 的内部 Neo4j ID	`INTEGER`	`4326`、`4979`、`7203`、`9157` 之一

示例

以下查询展示了如何提取*笛卡尔 2D* POINT 值的组件

查询

WITH point({x: 3, y: 4}) AS p
RETURN
  p.x AS x,
  p.y AS y,
  p.crs AS crs,
  p.srid AS srid

表 5. 结果
x	y	crs	srid
`3.0`	`4.0`	`"cartesian"`	`7203`
行数：1

以下查询展示了如何提取*WGS-84 3D* POINT 值的组件

查询

WITH point({latitude: 3, longitude: 4, height: 4321}) AS p
RETURN
  p.latitude AS latitude,
  p.longitude AS longitude,
  p.height AS height,
  p.x AS x,
  p.y AS y,
  p.z AS z,
  p.crs AS crs,
  p.srid AS srid

表 6. 结果
latitude	longitude	height	x	y	z	crs	srid
`3.0`	`4.0`	`4321.0`	`4.0`	`3.0`	`4321.0`	`"wgs-84-3d"`	`4979`
行数：1

空间值和索引

如果特定节点或关系属性上存在范围或点索引，并且空间点被分配给该节点或关系上的该属性，则该节点或关系将被索引。

在点索引中，Neo4j 使用 2D 或 3D 空间填充曲线在底层广义 B+树上。点索引针对距离和边界框查询进行了优化。更多信息请参见管理索引 → 点索引。

在范围索引中，点将根据其在每个坐标参考系统中的字典顺序进行排序。对于点值，此索引支持相等性检查。更多信息请参见管理索引 → 范围索引。

可比性和可排序性

Cypher 不支持使用不等于运算符（<、<=、> 和 >=）比较空间值。尝试这样做将返回 null。

要比较特定范围内的空间点，请改用空间函数point.distance 或 point.withinBBox。