Info Command

The info command generates a comprehensive summary of a VCDB v5 instance, providing key details about the data sored in the database, including available feature types, Levels of Detail (LoDs), feature and geometry counts, appearance information, generic attributes, the spatial extent of all features, and database metadata such as the coordinate reference system (CRS).

By default, the command prints a human-readable report to the console, but the same information can also be output in JSON format for automated workflows or programmatic use.

Synopsis

vcdb info [OPTIONS]

Options

The info command inherits global options from the main vcdb command. Additionally, it defines report and output options.

Global options

Option Description Default value

Option	Description	Default value
`[@<filename>…]`	One or more argument files containing options.
`-h`, `--help`	Show a help message and exit.
`-V`, `--version`	Print version information and exit.
`--config-file=<file>`	Load configuration from this file.
`-L`, `--log-level=<level>`	Log level: `fatal`, `error`, `warn`, `info`, `debug`, `trace`.	`info`
`--log-file=<file>`	Write log messages to this file.
`--quiet`	Disable console log messages.
`--pid-file=<file>`	Create a file containing the process ID.
`--plugins=<dir>`	Load plugins from this directory.
`--use-plugin=<plugin[=true\|false]> [,<plugin[=true\|false]>…]`	Enable or disable plugins with a matching fully qualified class name.	`true`

[@<filename>…]

One or more argument files containing options.

-h, --help

Show a help message and exit.

-V, --version

Print version information and exit.

--config-file=<file>

Load configuration from this file.

-L, --log-level=<level>

Log level: fatal, error, warn, info, debug, trace.

info

--log-file=<file>

Write log messages to this file.

--quiet

Disable console log messages.

--pid-file=<file>

Create a file containing the process ID.

--plugins=<dir>

Load plugins from this directory.

--use-plugin=<plugin[=true|false]> [,<plugin[=true|false]>…]

Enable or disable plugins with a matching fully qualified class name.

true

For more details on the global options and usage hints, see here.

Report options

Option Description Default value

Option	Description	Default value
`-o`, `--output=<file\|->`	Write output as a JSON file. Use `-` for `stdout`.
`--threads=<threads>`	Number of threads to use for parallel processing.	4
`-s`, `--feature-scope=<scope>`	Feature scope: `all`, `active`. For `active`, only properties of non-terminated features are considered.	`all`
`--include-generic-attributes`	Include generic attributes and their data types.
`--include-size-metrics`	Include database size metrics.

-o, --output=<file|->

Write output as a JSON file. Use - for stdout.

--threads=<threads>

Number of threads to use for parallel processing.

-s, --feature-scope=<scope>

Feature scope: all, active. For active, only properties of non-terminated features are considered.

all

--include-generic-attributes

Include generic attributes and their data types.

--include-size-metrics

Include database size metrics.

Database connection options

Option Description Default value

Option	Description	Default value
`-H`, `--db-host=<host>`	Name of the host on which the VCDB is running.
`-P`, `--db-port=<port>`	Port of the VCDB server.	5432
`-d`, `--db-name=<database>`	Name of the VCDB database to connect to.
`-S`, `--db-schema=<schema>`	Schema to use when connecting to the VCDB.	`citydb` or username
`-u`, `--db-username=<user>`	Username to use when connecting to the VCDB.
`-p`, `--db-password [=<password>]`	Password to use when connecting to the VCDB. Leave empty to be prompted.
`--db-property=<property=value> [,<property=value>…]`	Database-specific connection properties.

-H, --db-host=<host>

Name of the host on which the VCDB is running.

-P, --db-port=<port>

Port of the VCDB server.

5432

-d, --db-name=<database>

Name of the VCDB database to connect to.

-S, --db-schema=<schema>

Schema to use when connecting to the VCDB.

citydb or username

-u, --db-username=<user>

Username to use when connecting to the VCDB.

-p, --db-password [=<password>]

Password to use when connecting to the VCDB. Leave empty to be prompted.

--db-property=<property=value> [,<property=value>…]

Database-specific connection properties.

For more details on the database connection options and usage hints, see here.

Usage

Generating a database report

A database report is generated by executing the info command with the connection details of the target VCDB v5 instance.

Linux
Windows CMD

./vcdb info \
    -H localhost \
    -d citdb \
    -u citydb_user \
    -p mySecret

vcdb info ^
    -H localhost ^
    -d citdb ^
    -u citydb_user ^
    -p mySecret

The time required to generate a report depends on the size of the database. Reports are generally much faster to compute when indexes are enabled. If indexes are disabled, report generation may take considerably longer. Use the index command to check the current status of indexes and enable them as needed.

The report is displayed on the console in a human-readable format. It can also be generated in machine-readable JSON using the --output option. If a file path is provided for --output, the JSON report will be written to that file. If - is specified instead of a file path, the JSON report will be written to stdout. This JSON report can be easily piped to and processed by external tools.

The following examples demonstrate the usage of the --output option.

Linux
Windows CMD

./vcdb info [...] -o report.json      # write JSON to a file
./vcdb info [...] -o -                # write JSON to stdout
./vcdb info [...] -o - > report.json  # redirect stdout to a file

vcdb info [...] -o report.json      # write JSON to a file
vcdb info [...] -o -                # write JSON to stdout
vcdb info [...] -o - > report.json  # redirect stdout to a file

Report contents

The following example shows the structure of a JSON report generated by the info command. The human-readable version of the report printed to the console contains the same information in a more concise form.

{
  "metadata": {
    "generatedAt": "2025-08-21T07:51:40Z",
    "featureScope": "all",
    "genericAttributesProcessed": false
  },
  "summary": {
    "topLevelFeatures": [
      "bldg:Building"
    ],
    "lods": [
      "2",
      "3"
    ],
    "themes": [
      "Photovoltaic Potential",
      "Solar Thermal Potential",
      "rgbTexture"
    ],
    "crs": {
      "srid": 25833,
      "identifier": "urn:ogc:def:crs:EPSG::25833",
      "name": "ETRS89 / UTM zone 33N"
    },
    "extent": [
      778260.4775,
      5809001.5376,
      -703.348,
      823412.6066,
      5844145.0696,
      405.5
    ],
    "wgs84Extent": [
      19.087075,
      52.335758,
      19.782079,
      52.675649
    ]
  },
  "database": {
    "name": "VC Database",
    "version": "5.0.0",
    "dbms": {
      "name": "PostgreSQL",
      "version": "17.2",
      "properties": {
        "postgis": {
          "name": "PostGIS",
          "value": "3.5.0"
        },
        "postgis_sfcgal": {
          "name": "SFCGAL",
          "value": "n/a"
        }
      }
    },
    "hasChangelogEnabled": false,
    "connection": {
      "host": "localhost",
      "port": 5432,
      "database": "citydb",
      "schema": "citydb",
      "user": "citydb_user"
    }
  },
  "features": {
    "featureCount": {
      "active": 3476418,
      "terminated": 0
    },
    "topLevelFeatureCount": {
      "active": 539247,
      "terminated": 0
    },
    "byType": {
      "bldg:Building": {
        "active": 539247,
        "terminated": 0
      },
      "con:GroundSurface": {
        "active": 547284,
        "terminated": 0
      },
      "con:RoofSurface": {
        "active": 763994,
        "terminated": 0
      },
      "con:WallSurface": {
        "active": 1625893,
        "terminated": 0
      }
    }
  },
  "geometries": {
    "geometryCount": 3011975,
    "implicitGeometryCount": 0,
    "byType": {
      "core:MultiSurface": 2937193,
      "core:Solid": 74782
    },
    "byLod": {
      "2": 3011738,
      "3": 7
    }
  },
  "addresses": {
    "addressCount": 586034
  },
  "appearances": {
    "appearanceCount": 1617618,
    "hasGlobalAppearances": false,
    "hasMaterials": true,
    "hasTextures": true,
    "hasGeoreferencedTextures": false,
    "byTheme": {
      "Photovoltaic Potential": 539247,
      "Solar Thermal Potential": 539247,
      "rgbTexture": 539247
    }
  },
  "extensions": [],
  "codeLists": {},
  "modules": {
    "bldg": "http://3dcitydb.org/3dcitydb/building/5.0",
    "con": "http://3dcitydb.org/3dcitydb/construction/5.0",
    "core": "http://3dcitydb.org/3dcitydb/core/5.0"
  }
}

The JSON report is structured into sections, each summarizing a specific aspect of the database. The table below provides an overview and description of these sections.

Section Description

Section	Description
`metadata`	General information about the report, including the timestamp of generation, the scope of features considered, and whether generic attributes were processed.
`summary`	High-level overview of the database content, including top-level feature, available LoDs, appearance themes, CRS information, and spatial extent in both the database CRS and WGS84 coordinates.
`database`	Information about the connected database, including name and version, DBMS details including available extensions, VCDB properties such as whether changelog tracking is enabled, and connection details.
`features`	Counts of all features in the database, broken down into active vs. terminated, top-level features, and counts by feature type.
`geometries`	Statistics about geometries, including total count, count of implicit geometries, distribution by geometry type, and counts by LoD.
`addresses`	Total number of addresses stored in the database.
`appearances`	Detailed information about all appearances, including total number of appearances, presence of global appearances, materials, textures, georeferenced textures, and appearance counts broken down by theme.
`extensions`	List of all ADE extensions registered in the database, including name, version, and description. An empty array is included if no extensions are available.
`codeLists`	References to external codelists that are registered for appropriate CityGML data types in the database. An empty object is included if no codelists are available.
`modules`	List of VCDB module namespaces used by the data stored in the database. An empty object is included if no modules are used.

metadata

General information about the report, including the timestamp of generation, the scope of features considered, and whether generic attributes were processed.

summary

High-level overview of the database content, including top-level feature, available LoDs, appearance themes, CRS information, and spatial extent in both the database CRS and WGS84 coordinates.

database

Information about the connected database, including name and version, DBMS details including available extensions, VCDB properties such as whether changelog tracking is enabled, and connection details.

features

Counts of all features in the database, broken down into active vs. terminated, top-level features, and counts by feature type.

geometries

Statistics about geometries, including total count, count of implicit geometries, distribution by geometry type, and counts by LoD.

addresses

Total number of addresses stored in the database.

appearances

Detailed information about all appearances, including total number of appearances, presence of global appearances, materials, textures, georeferenced textures, and appearance counts broken down by theme.

extensions

List of all ADE extensions registered in the database, including name, version, and description. An empty array is included if no extensions are available.

codeLists

References to external codelists that are registered for appropriate CityGML data types in the database. An empty object is included if no codelists are available.

modules

List of VCDB module namespaces used by the data stored in the database. An empty object is included if no modules are used.

Feature scope

The --feature-scope option controls which features are considered when generating the report:

all: Includes all features in the VCDB, both active and terminated. All counts and derived statistics reflect the complete database. This is the default mode.
active: Includes only active features when computing statistics and properties. Terminated features are ignored for derived statistics such as top-level features, available LoDs, and other feature-based properties. However, overall feature counts still show both active and terminated features.

For example, if a specific LoD exists only for terminated features, it will not be included in an export of active features or be usable for filtering them. Consequently, this LoD does not appear in reports with active scope. This makes the active scope ideal for concise reports focused on current features, while the all scope provides a complete overview of the database.

Generating the report for only active features may take considerably more time.
For more information about terminating features, see the FEATURE table and the delete command.

Including generic attributes

The --include-generic-attributes option adds an additional genericAttributes section to the report. This section lists all generic attributes present in the database together with their data types as defined in the DATATYPE metadata table. Use this option when you need a complete overview of the generic attributes available in the database.

The example below shows an excerpt of the genericAttributes section.

{
  "metadata": {},
  "summary": {},
  ...
  "genericAttributes": {
    "ownerName": [
      "core:String"
    ],
    "roofHeight": [
      "core:Double"
    ],
    "energyPerformance": [ (1)
      "core:Integer",
      "core:String"
    ],
    ...
  }
}

1	In general, each generic attribute should be associated with a single data type. The presence of multiple data types usually indicates a consistency issue.

Depending on the number and complexity of generic attributes, generating the report may take more time.

Including database size metrics

Enabling the --include-size-metrics option appends a size subsection to the database section of the report. This subsection contains size values in bytes for the entire database, the selected schema, and individual tables. An example is shown below.

{
  "metadata": {},
  "summary": {},
  ...
  "database":{
    "name":"VC Database",
    "version":"5.0.0",
    ...
    "size":{
      "databaseSize":21454392467,
      "schemaSize":21436571648,
      "byTable":{
        "address":54951936,
        "appear_to_surface_data":2442379264,
        "appearance":283295744,
        "feature":3317882880,
        "geometry_data":2525831168,
        "implicit_geometry":32768,
        "property":6379757568,
        "surface_data":1938014208,
        "surface_data_mapping":3295518720,
        "tex_image":1198391296
      }
    }
  }
}

This option allows you to quickly evaluate the storage footprint of a VCDB v5 instance and its tables, which can be helpful for performance analysis, monitoring growth, or planning backups.

Controlling the report process

The info command offers the following options to control the report generation process:

--threads: Sets the number of threads for parallel processing to improve performance. By default, four threads are used independent of the number of processors available to the JVM.

Setting the number of threads too high can lead to performance issues due to thrashing. Additionally, each thread requires a separate database connection, so ensure your database can handle the required number of connections.