Skip to main content
输入输出别名
✔✗

​
说明

读取 GeoJSON FeatureCollection 文档，并为每个要素生成一行。每一行都具有以下固定 schema：
ColumnTypeDescription
idString要素的 id 成员 (JSON 字符串或数字) ，以文本形式存储；如果 id 不存在或为 null，则为空字符串。
geometryGeometry要素的几何对象，存储为 Geometry Variant 类型。
propertiesNullable(JSON)要素的 properties 对象，存储为半结构化 JSON 列。显式的 "properties": null 会保留为 NULL。
每个几何对象都存储在 ClickHouse 的 Geometry 类型中 (即 Variant) 。支持的 GeoJSON 几何类型包括 Point、LineString、MultiLineString、Polygon 和 MultiPolygon。另外两种 GeoJSON 几何类型 GeometryCollection 和 MultiPoint 无法用 Geometry 类型表示；默认情况下，将其读入 geometry 列时会引发异常，但也可以改为插入 NULL——请参见下方的处理不受支持的几何类型。默认情况下，只有当要素的几何对象是显式的 JSON null 时，geometry 列才为 NULL；在 input_format_geojson_unsupported_geometry_handling = 'null' 下，不受支持的几何类型也会被写为 NULL。 系统会校验文档结构：顶层 type 必须为 FeatureCollection，并且 features 中的每个元素都必须具有 type Feature。坐标必须满足 GeoJSON 的形状约束——LineString (以及 MultiLineString 中的每条线) 必须至少包含两个位置，而 Polygon 的 ring (以及 MultiPolygon 中的每个 ring) 必须闭合且至少包含四个位置。格式不正确的文档会被拒绝，而不会被静默加载。 FeatureCollection 对象中的其他键 (如 name 或 crs) 以及每个 Feature 对象中的其他键 (如 bbox) 都会被忽略。 键的顺序可以灵活调整：顶层 type 可以出现在 features 数组之前或之后；在几何对象内部，coordinates 也可以出现在 type 之前或之后。 schema inference 会返回上述固定 schema，因此 DESCRIBE 和 SELECT ... FROM format(...) 无需表定义即可使用。

​
示例用法

给定以下 GeoJSON 文件 london.geojson，其中包含多种几何类型： 
{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "id": "1",
            "geometry": {"type": "Point", "coordinates": [-0.0761, 51.5081]},
            "properties": {"name": "Tower of London", "feature_type": "landmark", "year_built": 1078}
        },
        {
            "type": "Feature",
            "id": "2",
            "geometry": {
                "type": "LineString",
                "coordinates": [[-0.2500, 51.4700], [-0.1800, 51.4900], [-0.1200, 51.5060], [-0.0700, 51.5050], [0.0000, 51.5100]]
            },
            "properties": {"name": "River Thames", "feature_type": "river", "length_km": 346}
        },
        {
            "type": "Feature",
            "id": "3",
            "geometry": {
                "type": "Polygon",
                "coordinates": [[[-0.1880, 51.5074], [-0.1533, 51.5074], [-0.1533, 51.5153], [-0.1880, 51.5153], [-0.1880, 51.5074]]]
            },
            "properties": {"name": "Hyde Park", "feature_type": "park", "area_km2": 1.42}
        }
    ]
}
我们可以查询该文件并查看几何类型：
Query
SELECT id, properties.name AS name, variantType(geometry) AS geo_type
FROM file('london.geojson', GeoJSON);
Response
┌─id─┬─name────────────┬─geo_type───┐
│ 1  │ Tower of London │ Point      │
│ 2  │ River Thames    │ LineString │
│ 3  │ Hyde Park       │ Polygon    │
└────┴─────────────────┴────────────┘
会自动识别文件扩展名 .geojson，因此可省略 format 参数：
Query
SELECT id, properties.name AS name, variantType(geometry) AS geo_type
FROM file('london.geojson');
我们可以使用 variantType 查看每个 Geometry 对象的底层类型：
Query
SELECT properties.name AS name, geometry, variantType(geometry)
FROM file('london.geojson', GeoJSON);
Response
Row 1:
──────
name:                  Tower of London
geometry:              (-0.0761,51.5081)
variantType(geometry): Point

Row 2:
──────
name:                  River Thames
geometry:              [(-0.25,51.47),(-0.18,51.49),(-0.12,51.506),(-0.07,51.505),(0,51.51)]
variantType(geometry): LineString

Row 3:
──────
name:                  Hyde Park
geometry:              [[(-0.188,51.5074),(-0.1533,51.5074),(-0.1533,51.5153),(-0.188,51.5153),(-0.188,51.5074)]]
variantType(geometry): Polygon
我们可以这样提取底层数据：
Query
SELECT properties.name AS name, variantType(geometry), geometry.Point, geometry.LineString, geometry.Polygon
FROM file('london.geojson', GeoJSON);
Response
Row 1:
──────
name:                  Tower of London
variantType(geometry): Point
geometry.Point:        (-0.0761,51.5081)
geometry.LineString:   []
geometry.Polygon:      []

Row 2:
──────
name:                  River Thames
variantType(geometry): LineString
geometry.Point:        (0,0)
geometry.LineString:   [(-0.25,51.47),(-0.18,51.49),(-0.12,51.506),(-0.07,51.505),(0,51.51)]
geometry.Polygon:      []

Row 3:
──────
name:                  Hyde Park
variantType(geometry): Polygon
geometry.Point:        (0,0)
geometry.LineString:   []
geometry.Polygon:      [[(-0.188,51.5074),(-0.1533,51.5074),(-0.1533,51.5153),(-0.188,51.5153),(-0.188,51.5074)]]
访问 Geometry 子列时，如果该行存储的是该类型，则返回该值；否则返回该类型的默认值——Point 为 (0,0)，基于数组的类型为 []——因此请使用 variantType(geometry) 来判断当前设置的是哪种类型。 我们也可以将 GeoJSON 数据摄取到表中：
Query
CREATE TABLE london
(
    id           String,
    geometry     Geometry,
    properties   Nullable(JSON),
    name         String MATERIALIZED properties.name,
    feature_type String MATERIALIZED properties.feature_type
)
ENGINE = MergeTree
ORDER BY id;

INSERT INTO london
SELECT id, geometry, properties
FROM file('london.geojson', GeoJSON);
然后按要素类型进行查询：
Query
SELECT name, feature_type, variantType(geometry) AS geo_type
FROM london
ORDER BY id;
Response
┌─name────────────┬─feature_type─┬─geo_type───┐
│ Tower of London │ landmark     │ Point      │
│ River Thames    │ river        │ LineString │
│ Hyde Park       │ park         │ Polygon    │
└─────────────────┴──────────────┴────────────┘
无需表定义，我们也可以推断 GeoJSON 数据的 schema：
Query
DESCRIBE format(GeoJSON, '{"type":"FeatureCollection","features":[]}');
Response
┌─name───────┬─type───────────┐
│ id         │ String         │
│ geometry   │ Geometry       │
│ properties │ Nullable(JSON) │
└────────────┴────────────────┘

​
处理不受支持的几何类型

某些有效的 GeoJSON 几何类型 — 例如 GeometryCollection 和 MultiPoint — 无法用 ClickHouse 的 Geometry 类型表示。你可以使用 input_format_geojson_unsupported_geometry_handling 设置，控制当这类几何对象必须存储到 geometry 列中时应如何处理。可能的值为：
  • 'throw' — 抛出异常 (默认)
  • 'null' — 为 geometry 列插入 NULL 值并继续解析
这种处理方式仅在读取 geometry 列时适用。当 geometry 不是请求输出的列时 (例如 SELECT id FROM ...) ，不受支持的几何对象仍会验证其格式是否正确，但不会触发该处理方式——既不会抛出异常，也不会插入 NULL，因为不会将任何几何值 materialize。
Last modified on June 25, 2026