Skip to content

Commit 98dda5b

Browse files
clausnagelclausnagel
committed
reflected latest schema changes
1 parent 8bbffca commit 98dda5b

File tree

3 files changed

+68
-31
lines changed

3 files changed

+68
-31
lines changed

‎docs/3dcitydb/db-functions.md

Lines changed: 52 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -50,10 +50,10 @@ an error occurred during the deletion process.
5050
successfully deleted entries as a `SETOF BIGINT`, allowing multiple entries to be deleted in a single operation.
5151

5252
All functions offer an optional `schema_name` parameter, allowing you to apply them to different database schemas within your
53-
PostgreSQL database. The provided target schema must contain a 3DCityDB `v5` instance. If the `schema_name` is omitted,
54-
the default schema `citydb` will be used.
53+
PostgreSQL database. The provided target schema must contain a 3DCityDB `v5` instance. For more information, see
54+
[below](#applying-functions-to-different-schemas).
5555

56-
The example below demonstrates how to easily delete features based on a query result:
56+
The following example demonstrates how to easily delete features based on a query result:
5757

5858
```sql
5959
-- delete a single feature by id
@@ -69,7 +69,7 @@ depends on the ratio between the number of entries to be deleted and the total n
6969
example, if the `id` array is very large and covers a significant portion of the table, it may be more efficient to use the
7070
single-`id` version or delete entries in smaller batches.
7171

72-
The following example demonstrates how to create a custom function to delete all buildings from the 3DCityDB
72+
The example below demonstrates how to create a custom function to delete all buildings from the 3DCityDB
7373
using the single-`id` version of `delete_feature`:
7474

7575
```sql
@@ -152,11 +152,9 @@ as additional utility functions to support these operations.
152152

153153
| Function | Return type | Description |
154154
|------------------------------------------------------------------------------------------------------------------|-------------|------------------------------------------------------------|
155-
| **`get_feature_envelope`**<br/> `(fid BIGINT, compute_envelope INTEGER, set_envelope INTEGER, schema_name TEXT)` | `GEOMETRY` | Returns the envelope geometry of a given feature |
155+
| **`get_feature_envelope`**<br/> `(fid BIGINT, schema_name TEXT, compute_envelope INTEGER, set_envelope INTEGER)` | `GEOMETRY` | Returns the envelope geometry of a given feature |
156156
| **`get_implicit_geometry_envelope`**<br/> `(gid BIGINT, ref_pt GEOMETRY, matrix JSON, schema_name TEXT)` | `GEOMETRY` | Returns the envelope geometry of a given implicit geometry |
157157
| **`get_envelope`**<br/> `(geom GEOMETRY, schema_name TEXT)` | `GEOMETRY` | Computes the envelope geometry for a given geometry |
158-
| **`get_envelope`**<br/> `(box BOX3D, schema_name TEXT)` | `GEOMETRY` | Converts a BOX3D geometry to an envelope geometry |
159-
| **`get_envelope`**<br/> `(geom1 GEOMETRY, geom2 GEOMETRY, schema_name TEXT)` | `GEOMETRY` | Computes the envelope geometry for two geometries |
160158

161159
The `get_feature_envelope` function returns the envelope of a feature. The feature's primary key `id` must be
162160
provided as input. When the `compute_envelope` parameter is set to `0` (default), the envelope currently stored in the
@@ -167,30 +165,29 @@ encloses the feature, and it can be directly used as the value for the `envelope
167165

168166
The `get_feature_envelope` function offers two more optional parameters: The `set_envelope` parameter specifies whether the
169167
computed envelopes should be used to update the `envelope` columns of the feature and its subfeatures (`1` for true, `0` for
170-
false; default: `0`). The `schema_name` parameter defines the target database schema to operate in, as explained above
171-
(default: `citydb`).
168+
false; default: `0`). The `schema_name` parameter defines the target database schema to operate in, as explained
169+
[below](#applying-functions-to-different-schemas).
172170

173171
The envelope of implicit geometries can be calculated using the `get_implicit_geometry_envelope` function. It
174172
requires the following inputs: the primary key `id` of the template geometry from the `GEOMETRY_DATA` table, a PostGIS `POINT`
175173
geometry specifying the real-world coordinates where the template should be placed (`ref_pt`), and a 3x4 row-major matrix (JSON
176174
double array) defining the rotation, scaling, and translation for the template (`matrix`).
177175

178176
The reference point and transformation matrix follow the format used for storing them in the `PROPERTY` table
179-
(see [here](feature-module.md#relationships)). Therefore, the values from the `PROPERTY` table can be
180-
directly used as input parameters.
177+
(see [here](feature-module.md#relationships)). Therefore, the values from the `PROPERTY` table can be directly used as input parameters.
181178

182-
The remaining `get_envelope` functions are utility functions used by the functions mentioned above. However, they
183-
can also be used on their own to compute the envelope for one or two geometries, or to convert a PostGIS `BOX3D`
184-
geometry into the envelope representation needed for the `envelope` column in the `FEATURE` table.
179+
The remaining `get_envelope` function is primarily used internally by the functions mentioned above. However, it
180+
can also be called directly to compute the envelope of a single geometry. The result is also returned in the
181+
format required by the `envelope` column of the `FEATURE` table.
185182

186183
## CRS functions
187184

188185
The `citydb_pkg` package provides functions for performing CRS operations on a 3DCityDB instance.
189186

190187
| Function | Return type | Description |
191188
|-----------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|-----------------------------------------------------|
192-
| **`change_schema_srid`**<br/>`(target_srid INTEGER, target_srs_name TEXT, transform INTEGER, schema_name TEXT)` | `SETOF VOID` | Updates the coordinate system for a database schema |
193-
| **`change_column_srid`**<br/>`(table_name TEXT, column_name TEXT, dim INTEGER, target_srid INTEGER, transform INTEGER, geom_type TEXT, schema_name TEXT)` | `SETOF VOID` | Updates the coordinate system for a geometry column |
189+
| **`change_schema_srid`**<br/>`(target_srid INTEGER, target_srs_name TEXT, schema_name TEXT, transform INTEGER)` | `SETOF VOID` | Updates the coordinate system for a database schema |
190+
| **`change_column_srid`**<br/>`(table_name TEXT, column_name TEXT, dim INTEGER, target_srid INTEGER, schema_name TEXT, transform INTEGER, geom_type TEXT)` | `SETOF VOID` | Updates the coordinate system for a geometry column |
194191
| **`check_srid`**<br/>`(srid INTEGER)` | `INTEGER` | Checks if a given `SRID` is valid |
195192
| **`is_coord_ref_sys_3d`**<br/>`(srid INTEGER)` | `INTEGER` | Checks if a a CRS is a true 3D system |
196193
| **`is_db_coord_ref_sys_3d`**<br/>`(schema_name TEXT)` | `INTEGER` | Checks if the CRS of the 3DCityDB is true 3D system |
@@ -220,9 +217,42 @@ table with the new values.
220217

221218
The `citydb_pkg` package also provides various utility functions as shown below.
222219

223-
| Function | Return type | Description |
224-
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|--------------------------------------------------------------------------------|
225-
| **`citydb_version`**<br/>`(OUT version TEXT, OUT major_version INTEGER, OUT minor_version INTEGER, OUT minor_revision INTEGER)` | `RECORD` | Returns the version of the 3DCityDB instance |
226-
| **`db_metadata`**<br/>`(schema_name TEXT, OUT srid INTEGER, OUT srs_name TEXT, OUT coord_ref_sys_name TEXT, OUT coord_ref_sys_kind TEXT, OUT wktext TEXT, OUT versioning TEXT)` | `RECORD` | Returns meta information about the 3DCityDB instance |
227-
| **`get_seq_values`**<br/>`(seq_name TEXT, seq_count BIGINT)` | `SETOF BIGINT` | Returns `n` sequence values from the given sequence |
228-
| **`get_child_objectclass_ids`**<br/>`(class_id INTEGER, skip_abstract INTEGER, schema_name TEXT)` | `SETOF INTEGER` | Returns the `id` values of all transitive subclasses of the given object class |
220+
| Function | Return type | Description |
221+
|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|-------------------------------------------------------------------------------------------|
222+
| **`citydb_version`**<br/>`(OUT version TEXT, OUT major_version INTEGER, OUT minor_version INTEGER, OUT minor_revision INTEGER)` | `RECORD` | Returns the version of the 3DCityDB instance |
223+
| **`db_metadata`**<br/>`(schema_name TEXT, OUT srid INTEGER, OUT srs_name TEXT, OUT coord_ref_sys_name TEXT, OUT coord_ref_sys_kind TEXT, OUT wktext TEXT, OUT versioning TEXT)` | `RECORD` | Returns meta information about the 3DCityDB instance |
224+
| **`get_seq_values`**<br/>`(seq_name TEXT, seq_count BIGINT)` | `SETOF BIGINT` | Returns `n` sequence values from the given sequence |
225+
| **`get_child_objectclass_ids`**<br/>`(class_id INTEGER, schema_name TEXT, skip_abstract INTEGER)` | `SETOF INTEGER` | Returns the `id` values of all transitive subclasses of the given object class |
226+
| **`get_current_schema`**() | `TEXT` | Returns the name of the active 3DCityDB schema as determined by the current `search_path` |
227+
| **`set_current_schema`**<br/>`(schema_name TEXT, local BOOLEAN)` | `SETOF VOID` | Sets the active 3DCityDB schema to the specified name by adjusting the `search_path` |
228+
229+
The functions `get_current_schema` and `set_current_schema` simplify managing the active 3DCityDB schema. While `get_current_schema`
230+
returns the schema currently set in the `search_path`, `set_current_schema` updates it to the specified name. The
231+
`local` parameter controls the scope of the change: when set to true (default), it applies the current transaction only;
232+
when false, it applies to the entire session until explicitly changed. Additionally, `set_current_schema` automatically
233+
includes required schemas like `citydb_pkg` and `public`.
234+
235+
## Applying functions to different schemas
236+
237+
The 3DCityDB supports using multiple data schemas within the same PostgreSQL database. The default schema
238+
is named `citydb`, while additional schemas can be freely named by the user. A setup script to create additional data
239+
schemas is included in the 3DCityDB software package and is documented [here](db-scripts.md#shell-scripts).
240+
241+
Most of the database functions described in this chapter accept an optional `schema_name` parameter to specify the
242+
target schema. If this parameter is provided, the function temporarily sets the database `search_path` to the given
243+
schema, making it the active schema for that operation. This change to the `search_path` applies only for the duration
244+
of the current transaction — not the entire session. This ensures that any change to the `search_path` remains isolated
245+
and does not affect other operations outside the transaction, helping to avoid unintended side effects.
246+
247+
If `schema_name` is omitted, the function uses the schema currently set in the `search_path`. This offers
248+
flexibility, allowing users to configure the search path according to their needs before calling any 3DCityDB
249+
database functions.
250+
251+
!!! note
252+
When setting up a 3DCityDB instance, the default schema is always `citydb`. If you are not working with multiple schemas, you
253+
can simply omit the `schema_name` parameter when calling functions — they will automatically operate on the `citydb` schema.
254+
For most users, this is the default and recommended approach for invoking the database functions.
255+
256+
!!! tip
257+
The utility functions `get_current_schema` and `set_current_schema` (see [above](#utility-functions)) are especially useful
258+
for users who prefer not to manage the `search_path` manually.

‎docs/3dcitydb/metadata-module.md

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -136,14 +136,16 @@ The example below shows the JSON definitions for the `Road` feature type and the
136136
"namespace": "http://3dcitydb.org/3dcitydb/transportation/5.0",
137137
"description": "Relates to the sections that are part of the Road.",
138138
"type": "core:FeatureProperty",
139-
"target": "tran:Section"
139+
"target": "tran:Section",
140+
"relationType": "contains"
140141
},
141142
{
142143
"name": "intersection",
143144
"namespace": "http://3dcitydb.org/3dcitydb/transportation/5.0",
144145
"description": "Relates to the intersections that are part of the Road.",
145146
"type": "core:FeatureProperty",
146-
"target": "tran:Intersection"
147+
"target": "tran:Intersection",
148+
"relationType": "contains"
147149
}
148150
]
149151
}
@@ -324,7 +326,7 @@ for the `"imageURI"` property in the `core:AbstractTexture` type:
324326
Properties of type `core:FeatureProperty` or `core:GeometryProperty` are used to link a feature to another feature or a
325327
geometry representation. The JSON objects for these properties must include an additional `"target"` property, which holds
326328
the identifier of the referenced feature type or geometry type as its value. The following two properties, taken from
327-
the `core:AbstractObject` feature type, illustrate this.
329+
the `core:AbstractSpace` feature type, illustrate this.
328330

329331
=== "Feature property"
330332

@@ -334,7 +336,8 @@ the `core:AbstractObject` feature type, illustrate this.
334336
"namespace": "http://3dcitydb.org/3dcitydb/core/5.0",
335337
"description": "Relates to surfaces that bound the space.",
336338
"type": "core:FeatureProperty",
337-
"target": "core:AbstractSpaceBoundary"
339+
"target": "core:AbstractSpaceBoundary",
340+
"relationType": "contains"
338341
}
339342
```
340343

@@ -350,6 +353,10 @@ the `core:AbstractObject` feature type, illustrate this.
350353
}
351354
```
352355

356+
In addition to the `"target"` property, a `core:FeatureProperty` also specifies the relationship to the target feature using
357+
the `"relationType"` property, which can be either `relates` or `contains`. The meaning and implications of each
358+
relationship type are further explained in the context of the `PROPERTY` table [here](feature-module.md#relationships).
359+
353360
!!! tip
354361
The [3DCityDB software package](../download.md#3dcitydb-database-scripts) includes a JSON Schema specification that defines
355362
the allowed structure of the schema mapping for feature types. You can find this schema file, named

‎docs/3dcitydb/relational-schema.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,11 +25,11 @@ Relation schema of the 3DCityDB `v5`.
2525
All tables of the relation schema are logically grouped into five modules, which are discussed in the
2626
following chapters:
2727

28-
- **Feature module**: Contains the core tables for storing feature information, excluding geometry and appearance data.
29-
- **Geometry module**: Contains tables for storing both explicit and implicit geometry data.
30-
- **Appearance module**: Contains tables for storing appearance information.
31-
- **Metadata module**: Holds meta-information about features and their properties.
32-
- **Codelist module**: Stores codelists with their corresponding values.
28+
- [**Feature module**](feature-module.md): Contains the core tables for storing feature information, excluding geometry and appearance data.
29+
- [**Geometry module**](geometry-module.md): Contains tables for storing both explicit and implicit geometry data.
30+
- [**Appearance module**](appearance-module.md): Contains tables for storing appearance information.
31+
- [**Metadata module**](metadata-module.md): Holds meta-information about features and their properties.
32+
- [**Codelist module**](codelist-module.md): Stores codelists with their corresponding values.
3333

3434
!!! note
3535
Although conceptually the database model is applicable to any database system, this chapter uses

0 commit comments

Comments
 (0)