---
warning: DO NOT CHANGE THIS MANUALLY, THIS IS GENERATED BY https://github.com/duckdb/community-extensions repository, check README there
title: cityjson
excerpt: |
  DuckDB Community Extensions
  Read, write, and query CityJSON, CityJSONSeq, FlatCityBuf, and CityParquet 3D city model files.

extension:
  name: cityjson
  description: Read, write, and query CityJSON, CityJSONSeq, FlatCityBuf, and CityParquet 3D city model files.
  version: 0.4.0
  language: C++
  build: cmake
  license: MIT
  maintainers:
    - HideBa

repo:
  github: cityjson/duckdb-cityjson
  ref: a1455e1a0896160660f4646d240f2fb85be34617

docs:
  hello_world: |
    -- Read a CityJSON file
    SELECT * FROM read_cityjson('buildings.city.json');

    -- Read a CityJSONSeq (line-delimited) file
    SELECT * FROM read_cityjsonseq('buildings.city.jsonl');

    -- Read a FlatCityBuf file, pushing a bounding box into its spatial index
    SELECT * FROM read_flatcitybuf('buildings.fcb',
      min_x => 84000, min_y => 444000, max_x => 84500, max_y => 444500);

    -- Extract geometries as WKB at a specific Level of Detail
    SELECT * FROM read_cityjson('buildings.city.json', lod=>'1.2');

    -- Write query results to CityJSONSeq; the source CRS and metadata travel too
    COPY (SELECT * FROM read_cityjson('buildings.city.json'))
      TO 'output.city.jsonl' (FORMAT cityjsonseq);

    -- Inspect file metadata
    SELECT * FROM cityjson_metadata('buildings.city.json');

    -- Read material and texture definitions
    SELECT * FROM cityjson_materials('buildings.city.jsonl');

    -- Build a CityParquet package: a schema you can validate, mutate and write out
    CREATE SCHEMA city;
    CREATE TABLE city.building AS SELECT * FROM read_cityjson('buildings.city.json');
    PRAGMA cityparquet_init('city');
    PRAGMA cityparquet_validate('city');
    SELECT * FROM cityparquet_write('city', 'out/city');

  extended_description: |
    The CityJSON extension provides table functions for reading and writing 3D city model files
    in CityJSON (.city.json), CityJSONSeq (.city.jsonl), and FlatCityBuf (.fcb) formats, and for
    building CityParquet packages. CityJSON is a JSON-based encoding for 3D city models
    (buildings, terrain, vegetation, etc.) based on the CityGML data model.

    Reading and writing:
    - `read_cityjson`, `read_cityjsonseq`, `read_flatcitybuf` — table functions for querying city objects
    - `cityjson_metadata`, `cityjsonseq_metadata`, `flatcitybuf_metadata` — inspect file headers
    - `COPY ... TO` with formats `cityjson`, `cityjsonseq`, and `flatcitybuf` — write query results

    Appearance:
    - `cityjson_materials`, `cityjson_textures`, `cityjson_geometry_templates` — sidecar readers
    - Per-LoD `material_lod*` / `texture_lod*` reference columns, or `appearance := 'sidecar'`
      to normalise appearance into sidecar tables with global ids and inlined UV coordinates

    CityParquet packages — a package is a DuckDB schema, so it is queryable while you build it:
    - `cityparquet_init`, `cityparquet_read`, `cityparquet_write` — create, load and write a package
    - `insert_cityjson`, `insert_cityjsonseq`, `insert_flatcitybuf` — add a file, routed by CityGML module
    - `cityparquet_validate`, `cityparquet_reconcile`, `cityparquet_orphans`, `cityparquet_vacuum`
    - `cityparquet_delete` (with cascade) and `cityparquet_merge`
    - `cityjson_geoparquet_geo` — the GeoParquet `geo` and CityParquet `city` footer objects

    Additional features:
    - Automatic schema inference from CityJSON attributes
    - Wide columnar layout: one WKB geometry column per Level of Detail, plus a per-object `bbox` extent
    - `geometry_properties_lod*` as a native STRUCT, so semantic surfaces and shells are columns
    - Spatial and attribute-query pushdown on FlatCityBuf, using the file's R-tree and B+tree indexes
    - Selective deserialisation: a query projecting no geometry never decodes it
    - Filter pushdown on `id`, `feature_id`, and `object_type`
    - Streaming reads of large CityJSONSeq files and remote files over HTTP/S3/GCS
    - CRS handling follows GeoParquet's tri-state convention, so a georeferenced file never
      silently claims OGC:CRS84
    - Support for CityJSON v2.0 and CityJSONSeq formats

    Full documentation — every function, its parameters and its output schema — is at
    [cityjson.github.io/duckdb-cityjson](https://cityjson.github.io/duckdb-cityjson/).
    For more information on the CityJSON format, see https://www.cityjson.org/.

extension_star_count: 11
extension_star_count_pretty: 11
extension_download_count: 853
extension_download_count_pretty: 853
image: '/images/community_extensions/social_preview/preview_community_extension_cityjson.png'
layout: community_extension_doc
---
### Compatibility Matrix

This table covers all DuckDB releases that have not reached [end-of-life](https://duckdb.org/release_calendar), including LTS releases, and shows the 2 most recent patch releases of each. Older patch releases are not listed, but the extension may be available for them as well.

<div class="extension_compatibility_table"></div>

| Platform | 1.4.4 | 1.4.5 | 1.5.5 | 1.5.6 | 2.0.0 |
| :--- | :---: | :---: | :---: | :---: | :---: |
| Linux AMD64 | ❌ | ❌ | ✅ | ✅ | ❌ |
| Linux ARM64 | ❌ | ❌ | ✅ | ✅ | ❌ |
| macOS AMD64 | ❌ | ❌ | ✅ | ✅ | ❌ |
| macOS ARM64 | ❌ | ❌ | ✅ | ✅ | ❌ |
| Windows AMD64 | ❌ | ❌ | ✅ | ✅ | ❌ |
| Windows ARM64 | ❌ | ❌ | ❌ | ❌ | ❌ |
| WebAssembly | ❌ | ❌ | ✅ | ✅ | ❌ |

### Installing and Loading
```sql
INSTALL {{ page.extension.name }} FROM community;
LOAD {{ page.extension.name }};
```

{% if page.docs.hello_world %}
### Example
```sql
{{ page.docs.hello_world }}```
{% endif %}

{% if page.docs.extended_description %}
### About {{ page.extension.name }}
{{ page.docs.extended_description }}
{% endif %}
### Added Functions

<div class="extension_functions_table"></div>

|         function_name         | function_type | description | comment | examples |
|-------------------------------|---------------|-------------|---------|----------|
| cityjson_appearance_ids       | scalar        | NULL        | NULL    |          |
| cityjson_geometry_templates   | table         | NULL        | NULL    |          |
| cityjson_geoparquet_geo       | table         | NULL        | NULL    |          |
| cityjson_materials            | table         | NULL        | NULL    |          |
| cityjson_metadata             | table         | NULL        | NULL    |          |
| cityjson_shift_appearance_ids | scalar        | NULL        | NULL    |          |
| cityjson_textures             | table         | NULL        | NULL    |          |
| cityjson_wkb_extent           | scalar        | NULL        | NULL    |          |
| cityjson_wkb_geometry_type    | scalar        | NULL        | NULL    |          |
| cityjsonseq_metadata          | table         | NULL        | NULL    |          |
| cityparquet_city_field        | scalar        | NULL        | NULL    |          |
| cityparquet_delete            | pragma        | NULL        | NULL    |          |
| cityparquet_delete_sql        | scalar        | NULL        | NULL    |          |
| cityparquet_init              | pragma        | NULL        | NULL    |          |
| cityparquet_init_sql          | scalar        | NULL        | NULL    |          |
| cityparquet_merge             | pragma        | NULL        | NULL    |          |
| cityparquet_merge_sql         | scalar        | NULL        | NULL    |          |
| cityparquet_orphans           | pragma        | NULL        | NULL    |          |
| cityparquet_read              | pragma        | NULL        | NULL    |          |
| cityparquet_reconcile         | pragma        | NULL        | NULL    |          |
| cityparquet_reconcile_sql     | scalar        | NULL        | NULL    |          |
| cityparquet_vacuum            | pragma        | NULL        | NULL    |          |
| cityparquet_vacuum_sql        | scalar        | NULL        | NULL    |          |
| cityparquet_validate          | pragma        | NULL        | NULL    |          |
| cityparquet_validate_sql      | scalar        | NULL        | NULL    |          |
| cityparquet_write             | table         | NULL        | NULL    |          |
| flatcitybuf_metadata          | table         | NULL        | NULL    |          |
| insert_cityjson               | pragma        | NULL        | NULL    |          |
| insert_cityjson_sql           | scalar        | NULL        | NULL    |          |
| insert_cityjsonseq            | pragma        | NULL        | NULL    |          |
| insert_flatcitybuf            | pragma        | NULL        | NULL    |          |
| read_cityjson                 | table         | NULL        | NULL    |          |
| read_cityjsonseq              | table         | NULL        | NULL    |          |
| read_flatcitybuf              | table         | NULL        | NULL    |          |

### Overloaded Functions

<div class="extension_functions_table"></div>

This extension does not add any function overloads.

### Added Types

<div class="extension_types_table"></div>

This extension does not add any types.

### Added Settings

<div class="extension_settings_table"></div>

This extension does not add any settings.