Metadata

Relation metadata provides supplementary, context-dependent information about database relations in Centia.io.

Metadata is stored outside the physical database schema and does not affect table structure, constraints, or storage. Instead, it is consumed by clients such as admin interfaces, map viewers, SDKs, query builders, and automation tools.

Each metadata entry is keyed by the fully qualified relation name: <schema>.<relation>.

Endpoint

HTTP

Get Metadata

GET /api/v4/meta/{query}

query can be a schema qualified relation name, a schema name, a tag in the form tag:name or combination of the three separated by comma.

Example Request: GET /api/v4/meta/my_schema

Updating Metadata

To update metadata, use the PATCH method. You can update relation-level attributes and field-level metadata. System metadata is read-only and cannot be modified.

HTTP

Update Relation Metadata

PATCH /api/v4/meta HTTP/1.1
Content-Type: application/json

{
  "relations": {
    "my_schema.my_relation": {
      "title": "New Relation Title",
      "abstract": "Updated description",
      "fields": {
        "id": {
          "alias": "Identifier",
          "sort_id": 10
        }
      },
      "properties": {
        "custom_key": "new_value"
      }
    },
    "my_schema.my_other_relation": {
      "title": "Another new Relation Title",
      "abstract": "Updated description",
      "fields": {
        "id": {
          "alias": "Identifier",
          "sort_id": 10
        }
      },
      "properties": {
        "custom_key": "new_value"
      }
    }
  }
}

Updateable Fields

Only the following sections can be updated:

1. Relation-level metadata: title, abstract, group, sort_id, tags, and the properties object.
2. Field metadata: alias, queryable, and sort_id for individual fields.

Any attempt to update system metadata (fields starting with _) will be ignored.

Metadata Sections

A relation metadata object consists of three conceptual sections:

1. Relation-level metadata: User-defined attributes describing the relation.
2. Field metadata: Descriptions of individual columns.
3. System metadata: Read-only attributes generated from the data source.

1. Relation-level metadata

These are user-defined, contextual attributes describing the relation.

Property	Type	Description
title	string | null	Human-readable title
abstract	string | null	Description or summary
group	string | null	Logical grouping (e.g. UI category)
sort_id	integer | null	Sorting weight
tags	string[]	Classification tags
properties	object	Free-form key/value metadata

Example:

{
    "title": null,
    "abstract": "Example description of the relation",
    "group": "My Group",
    "sort_id": 100,
    "tags": ["tag1", "tag2"]
}

Properties object

The properties container is for arbitrary user-defined attributes.

• Keys are user-defined.
• Values may be string, numeric, or boolean.
• Semantics are defined by the consuming application.

Example:

{
    "properties": {
        "feature_flag": true,
        "external_id": 12345,
        "owner": "Martin Høgh"
    }
}

System metadata

System metadata is generated automatically from the underlying data source and is read-only.

Property	Type	Description
_uuid	string	Internal relation UUID
_schema	string	Schema name
_rel	string	Relation name
_rel_type	string	Relation type (TABLE, VIEW, etc.)
_pkey	string	Primary key column

Geometry metadata

Present for spatial relations (relations with a geometry field).

Property	Type	Description
_geometry_column	string	Geometry column name
_geom_type	string	Geometry type (e.g. POINT)
_coord_dimension	integer	Coordinate dimension
_srid	integer	Spatial reference ID (SRID)

Example:

{
    "_geometry_column": "the_geom",
    "_geom_type": "POINT",
    "_coord_dimension": 2,
    "_srid": 25832
}

Security metadata

Property	Type	Description
_authentication	string	Relation access level (e.g. Read, Write, Read/write)

2. Field metadata

Field metadata describes individual columns within the relation. It consists of user-defined attributes and system-generated attributes.

User-defined field attributes

These attributes can be updated via the PATCH endpoint.

Property	Type	Description
alias	string | null	Display label used in UI
queryable	boolean	Whether the field can be filtered/searched
sort_id	integer | null	Field sort order within the list

Example:

{
    "fields": {
        "id": {
            "alias": "Primary ID",
            "queryable": false,
            "sort_id": 1000
        }
    }
}

System field metadata

System field metadata is generated automatically from the database catalog and is read-only. These attributes are prefixed with _ and provide introspection details for each column.

Property	Type	Description
_type	string	PostgreSQL data type (e.g. integer, character varying, geometry)
_character_maximum_length	integer | null	Maximum character length (for character types)
_numeric_precision	integer | null	Numeric precision (for numeric types)
_numeric_scale	integer | null	Numeric scale (for numeric types)
_max_bytes	integer | null	Maximum byte size of the column
_is_unique	boolean	Whether the column has a unique constraint
_is_nullable	boolean	Whether the column allows NULL values
_default_value	string | null	Default value expression (e.g. nextval('seq'::regclass), now())

Example:

{
    "fields": {
        "gid": {
            "alias": "GID",
            "queryable": false,
            "sort_id": 0,
            "_type": "integer",
            "_character_maximum_length": null,
            "_numeric_precision": 32,
            "_numeric_scale": 0,
            "_max_bytes": 4,
            "_is_unique": true,
            "_is_nullable": false,
            "_default_value": "nextval('my_table_gid_seq'::regclass)"
        }
    }
}

Full Example Response

{
    "relations": {
        "geofa.test": {
            "title": null,
            "abstract": "Example relation description",
            "group": "Demo Group",
            "sort_id": 100,
            "tags": ["demo", "test"],
            "properties": {
                "custom_key": "custom_value"
            },
            "fields": {
                "gid": {
                    "alias": null,
                    "queryable": false,
                    "sort_id": null,
                    "_type": "integer",
                    "_character_maximum_length": null,
                    "_numeric_precision": 32,
                    "_numeric_scale": 0,
                    "_max_bytes": 4,
                    "_is_unique": true,
                    "_is_nullable": false,
                    "_default_value": "nextval('test_gid_seq'::regclass)"
                },
                "id": {
                    "alias": "ID TEST",
                    "queryable": false,
                    "sort_id": 1000,
                    "_type": "integer",
                    "_character_maximum_length": null,
                    "_numeric_precision": 32,
                    "_numeric_scale": 0,
                    "_max_bytes": 4,
                    "_is_unique": false,
                    "_is_nullable": true,
                    "_default_value": null
                }
            },
            "_uuid": "3f13e92e-ddad-4b26-a4e3-bd8b29f8f28a",
            "_schema": "geofa",
            "_rel": "test",
            "_geometry_column": "the_geom",
            "_pkey": "gid",
            "_rel_type": "TABLE",
            "_coord_dimension": 2,
            "_geom_type": "POINT",
            "_srid": 25832,
            "_authentication": "Read/write",
            "_children": null
        }
    }
}

Semantics and Usage

Relation metadata does not:

• Modify the database schema.
• Create or alter columns.
• Affect physical storage or indexing.

It is interpreted purely by higher-level services such as admin dashboards, map clients, SDKs, and code generators.