Database Import

A Database Import Task imports features into one of the configured databases.

Step 1 (Task name)

Option Description

Task Name

Name of the task.

Create or overwrite Datasource

Select whether to create a new datasource or overwrite an existing one

Datasource Name

If an existing data source is to be overwritten, select the source here.

Click NEXT STEP to continue.

Step 2 (Database)

In this step, the target database for the import process must be selected.

Select Database

Choose the database where the data will be imported.

The system lists the available configured databases. Select the appropriate one from the dropdown menu.

If the required database is not listed, it must first be configured in the administration section.
See Database Management for instructions on how to create and manage database connections.

Validate Connection to Database

After selecting the database, click Validate Connection to Database to verify that the connection is working properly. This validation is optional but recommended.

This step ensures:

  • The database is reachable

  • Credentials are correct

  • The import task can be executed without connection issues

Once the connection is successfully validated, click NEXT STEP to continue.

Step 3 (Task settings)

In this step, configure the input data and the import options.

Select Import File or Directory

Select the input source for the import:

Input source Behavior Notes

File

Imports exactly the selected file.

The file extension does not matter, but the content must match a supported CityGML/CityJSON version for the selected database and (if applicable) the selected format.

Directory

Scans the selected directory recursively and imports all supported files.

Supported files are detected based on their file extension (see below).

ZIP archive

Scans the archive recursively like a directory and imports all supported files.

Supported files are detected based on their file extension (see below).

When scanning a directory or ZIP archive, the Publisher searches for input files based on their file extension:

Format File extensions (directory/ZIP scan)

CityGML

.gml, .xml, .gz, .gzip, .zip

CityJSON (incl. CityJSONSeq)

.json, .jsonl, .gz, .gzip, .zip

Format

Database Supported input formats Default Behavior

VCDB 4

CityGML 1.0/2.0, CityJSON 1.0

n/a

  • There is no Format selection list.

  • You can provide a supported CityGML or CityJSON input file.

  • If a directory or ZIP archive is selected as input, CityGML and CityJSON files are detected and processed (if their format version is supported).

VCDB 5

CityGML 1.0/2.0/3.0, CityJSON 1.0/1.1/2.0

CityGML (1.0/2.0/3.0)

  • The Format selection list is available: CityGML (1.0/2.0/3.0) or CityJSON (1.0/1.1/2.0).

  • The selected format restricts which input files are accepted. If you select CityGML but provide a CityJSON file (or vice versa), the task will abort with an error.

  • If a directory or ZIP archive is selected as input, only files matching the selected format are considered (based on the file extensions listed above).
For VCDB 5 databases, CityJSON 1.1/2.0 import supports CityJSON Text Sequences (CityJSONSeq) / *.jsonl.

Import Mode

The import mode defines how incoming features interact with existing features in the database.

Duplicates are detected based on the identifier of a feature:

  • CityGML: gml:id

  • CityJSON: the key in the "CityObjects" collection (CityJSON) or the "id" of "CityJSONFeature" objects (CityJSONSeq)

Terminated features are excluded from the duplicate check.

Four modes are available:

Option Description Default value

Import All

  • Imports all features from the input files.

  • If a duplicate identifier is found, a duplicate feature is created (no update or deletion takes place).

  • Use when: Initial imports and data loads where duplicates are acceptable.

Default

Skip Existing

  • Features already in the database take precedence.

  • If a duplicate identifier is found, the feature from the input file is skipped.

  • Use when: Extending the dataset without modifying existing data.

Delete Existing

  • Input features take precedence.

  • If a duplicate identifier is found, the existing feature in the database is deleted first.

  • The feature from the input file is then imported.

  • Use when: Replacing existing features without keeping history.

Terminate Existing

  • Similar to Delete Existing, but terminates the existing feature instead of deleting it.

  • The existing feature remains in the database and gets a termination time, preserving its history.

  • The feature from the input file is then imported.

  • Use when: Maintaining historical records.

Import Options

These settings control performance and processing behavior.

Option Description Default value VCDB 4 VCDB 5 Input format

Preview mode

Run the import in preview mode. Features are parsed and validated, but not written to the database.

Off

No

Yes

CityGML, CityJSON

Deactivate indices and automatically reactivate

If enabled, indices are deactivated before processing and automatically reactivated after the import is finished.

This can improve performance for large imports, but may add overhead for smaller incremental imports.

Off

Yes

Yes

CityGML, CityJSON

Number of Threads

Number of parallel threads used during import. Each thread requires a separate database connection.

4

Yes

Yes

CityGML, CityJSON

Log Level

Defines the minimum severity of events that are shown in the task log. All messages of that severity or higher are included.

See Log Level below.

info

Yes

Yes

CityGML, CityJSON

Fail fast on errors

If enabled, stop the import immediately when an error occurs.

Off

Yes

Yes

CityGML, CityJSON

Compute and replace envelopes

If enabled, envelopes (feature extents) are computed from the geometries during import and overwrite extents read from the input files.

On

No

Yes

CityGML, CityJSON

Map unsupported types to generics

If enabled, city objects from unsupported CityJSON extensions are mapped to generic city objects. Unknown extension attributes are stored as generic attributes.

Off

No

Yes

CityJSON

Read appearances

If enabled, appearance information (textures, materials) is imported as well.

On

Yes

Yes

CityGML, CityJSON

Themes

Optional list of appearance themes to import (comma-separated).

If left empty, all appearances are imported. Use none to include appearances that do not have a theme.

Only relevant when Read appearances is enabled.

(empty)

No

Yes

CityGML, CityJSON

Log Level

Defines the minimum severity of events that are shown in the task log. All messages of that severity or higher are included.

The available log levels, ordered from highest to lowest severity, are:

Level Description Default value

fatal

Critical errors causing immediate termination (least output).

error

Non-recoverable errors.

warn

Warnings about potential issues.

info

General operational messages.

Default

debug

Detailed debugging information.

trace

Most detailed logs for troubleshooting.
Use debug or trace for debugging or in support cases.

Metadata

Optional metadata fields for documenting the import process:

Option Description Default value

Data lineage or origin of features

Lineage of the imported data (origin information stored with the features).

Updating person

Name of the responsible person performing the import.

Database user

Reason for update

Explanation of why this import is being performed.

For VCDB 5 databases, the lineage field supports the following placeholders, which are automatically replaced during import:

Placeholder Description

@file_path@

Absolute path to the input file.

@file_name@

Name of the input file.

@content_path@

Full logical path to the imported content, including ZIP entries if applicable.

@content_name@

Name of the imported content, e.g., the file name or the name of the ZIP entry.

The file_* and content_* placeholders produce identical results for regular files. For ZIP archives, the file_* placeholders refer to the ZIP file itself, while the content_* placeholders refer to the specific file inside the archive.

Filter Options

These options allow restricting the import to a subset of features.

Option Description Default value

Feature IDs

Comma-separated list of feature identifiers to import.

Feature Types

One or more feature types to import.

Examples (as shown in the UI):

  • Building

  • Bridge

  • CityFurniture

  • CityObjectGroup

  • GenericCityObject

Bounding Box

Spatial filter defined as x_min,y_min,x_max,y_max in EPSG:4326 coordinates (WGS84). The Publisher UI currently supports EPSG:4326 only.

Use Get bounding box from database (Get from database) icon to automatically fill the bounding box with the spatial extent of the data in the selected database.
Click on Edit bounding box (Edit bounding box) icon to open the map editor and draw or adjust the extent.

Off

Bounding Box Mode

Defines how the bounding box filter is applied:

  • Intersects: Process features whose bounding box overlaps the filter bounding box.

  • Contains: Process only features that are fully inside the filter bounding box.

  • On Tile (VCDB 5 only): Process features whose bounding box center lies within the filter bounding box.

Intersects

Count limit

Restricts the number of processed features and optionally skips a number of features at the beginning of the result set.

Use:

  • Limit: Maximum number of features to process (default: 1000).

  • Start index: 0-based index of the first feature to process within the filtered result set (default: 0).

Off
The limit and start index apply across all input files and can be used separately or together. This enables pagination-style imports when working with large datasets.
When using multiple filters, all conditions must be satisfied for a feature to be imported.
Filters are applied only to top-level features in the input files. Matching features are imported together with their contained subfeatures (CityGML) or 2nd-level city objects (CityJSON). Filtering subfeatures / 2nd-level city objects is not supported.

CityGML Upgrade Options

These options are only available for CityGML imports into a VCDB 5 database.

They help resolve compatibility issues when importing data that originally comes from CityGML 2.0 or 1.0.

Option Description Default value

Use LoD4 as LoD3

Use LoD4 as LoD3, replacing an existing LoD3.

Off

Map LoD0 Roof Edge

Map LoD0 roof edges onto roof surfaces.

Off

Map LoD1 MultiSurfaces

Map LoD1 multi-surfaces onto generic thematic surfaces.

Off

Create city object relations

If enabled, relations between imported city objects are created during the import.

On

Resolve cross LoD references

If enabled, references between different Levels of Detail (LoD) are resolved during the import.

On
For more information about these options, refer to the VC Database documentation on CityGML upgrade options.

Click NEXT STEP to continue.

Step 4 (Task schedule)

Option Description

Start Job as soon as possible

Start the job immediately.

Start Job once at given time

Schedule job for a future time.

Repeat Job

Automatic periodic execution of the job.

Publish Job after Completion

Once conversion is successful, the datasource is published automatically.