Skip to content

Funktionen_CollectionResource

Jump to bottom
Florian Fehring edited this page Apr 30, 2026 · 12 revisions

Here you find documentation for working with collections. Collections are spaces in database that contain records (datasets). Postgres: collection = table

Function 1: Create a Collection

URL: {{base_url}}/{{smartdata}}/smartdata/collection/testcollection_ts?storage=teststorage

Method: POST

Body: JSON with attribute definition (see examples)

  1. Send POST request with attribute definitions
    • Creates the collection. Identity attribute "id" is automatically added.
    • Response state: 201 CREATED

A attribute definition consists of the following informations:

Name Description Possible Values Default value Optional
isIdentity If that attribute is an identity attribute true / false false yes
isAutoIncrement If that attribute has auto incremention values true / false false yes
isNullable It attribute can be null true / false true yes
name attributes name all chars - no
type attributes datatype all supported by underlying db - no
defaultValue default value for atribute every matching to datatype yes yes

Common types: bigserial, timestamp, float8, int8, varchar, bool

Common attributes:

  • id (Id attributes default name for id based functions)
  • ts (Timestamp values default name used for time based functions)

Testcases:

  • testCreateCollection()

Exceptions:

  1. Try to create a collection that allready exists
    • Response state: NOT_MODIFIED
    • testCreateCollectionAllreadyExists()
  2. A autoincrementing attribut is given with the definition
    • Collection will be created with autoincrementation attribute
    • testCreateCollectionGivingAutoId()
  3. A non autoincrementing attribut is given with the definition
    • Collection will be created with non autoincrementation attribute
    • testCreateCollectionGivingId()

Function 2: Create a Collection with geo information

This is only supported on systems with geospatial ability.

URL: {{base_url}}/{{smartdata}}/smartdata/collection/testcollection_ts?storage=teststorage

Method: POST

Body: JSON with attribute definition (see examples)

  1. Send POST request with attribute definitions
    • Creates the collection with given geometry attributes
    • Response state: 201 CREATED

A attribute definition can use the following informations additionaly to the base informations:

Name Description Possible Values Default value Optional
type attributes datatype geometry(Point,4326), geometry(PointZ,4326) - false

Geometry types are database depending. postgres: You can use every geometry type that is supported by postgis.

Function 3: Getting collections attributes

URL: {{base_url}}/{{smartdata}}/smartdata/collection/testcollection_ts?storage=teststorage

Method: GET

  1. Sending GET request
    • Respons with an list of attributes and their definition (JSON)
    • Response state: 200 OK

The returned JSON can be used to create a new table with the same attributes.

Testcases:

  • testGetAttributes()

Exceptions:

  1. There are no attributes in the collection
    • Response with an empty list
    • Response state: 200 OK
  2. The collection or storage used does not exist
    • Response with error message
    • Response state: 404 NOT FOUND
    • testGetAttributesNoExSchema()

Function 4: Get attributes with geoinformation from collection

URL: {{base_url}}/{{smartdata}}/smartdata/collection/testcollection_geometries?storage=teststorage

Method: GET

  1. Sending GET request
    • Respons with an list of attributes and their definition (JSON) including advanced info about geometry columns
    • Response state: 200 OK

In this case attributes have always type "geometry" with additional informations:

  • subtype: POINT, POINTZ, ...
  • dimension: 2,3 (2D/3D)
  • srid: A number identifying the coordinate system

Testcase:

  • testGetGeoAttributes()

Exceptions:

  1. There are no attributes in the collection
    • Response with an empty list
    • Response state: 200 OK
  2. The collection or storage used does not exist
    • Response with error message
    • Response state: 404 NOT FOUND
    • testGetAttributesNoExSchema()

Function 5: Add a new attribute

URL: {{base_url}}/{{smartdata}}/smartdata/collection/testcollection_ts/addAttributes?storage=teststorage

Method: PUT

Body: New attribut(s) definition in array

  1. Sending PUT request
    • New attributes are added
    • Response state: 201 CREATED

Testcases:

  • testAddAttributes()

Exceptions:

  1. New attribute has invalid definition:
    • Response with error message
    • Response state: PRECONDITION_FAILED
  2. One on the new attributes allready exists
    • Response with error message
    • Response state: CONFLICT

Function 6: Add a new Geo-Attribut

URL: {{base_url}}/{{smartdata}}/smartdata/collection/testcollection_ts/addAttributes?storage=teststorage

Method: PUT

Body: New attribut(s) definition in array

  1. Sending PUT request
    • New attributes are added
    • Response state: 201 CREATED

Testcase:

  • testAddGeoAttributes()

Exceptions:

  1. New attribute has invalid definition:
    • Response with error message
    • Response state: PRECONDITION_FAILED
  2. One on the new attributes allready exists
    • Response with error message
    • Response state: CONFLICT

Function 7: Change attribute

URL: {{base_url}}/{{smartdata}}/smartdata/collection/testcollection_ts/changeAttribute?storage=teststorage

Method: PUT

Body: Changed column definition

  1. Sending PUT request
    • Attribute changes it's type, length, defaultValue or any other information
    • Response state: 200 OK

Exceptions:

  1. New information is invalid definition:
    • Response with error message
    • Response state: PRECONDITION_FAILED

Function 8: Change SRID of an Geo-Attribute

URL: {{base_url}}/{{smartdata}}/smartdata/collection/testcollection_geometries/changeAttribute?storage=teststorage

Method: PUT

Body: Changed column definition

  1. Sending PUT request
    • Attribute changes its SRID, existing coordinates are converted
    • Response state: 200 OK

Testcases:

  • testChangeSRID()

Exceptions:

  1. New srid is invalid definition:
    • Response with error message
    • Response state: PRECONDITION_FAILED

Function 9: Delete an attribute

URL: {{base_url}}/{{smartdata}}/smartdata/collection/testcollection_geometries/changeAttribute?storage=teststorage

Method: PUT

Body: JSON array with one object for each deleteable attribut with it's name.

  1. Sending PUT request
    • Attributes are removed from collection
    • Response state: 200 OK

Function 10: Copy a collection

Use function 3 and function 1 for this. This works even over different storages and different SmartData instances.

  1. Get the collection definition via GET /collection/TABLE_NAME
  2. Send the recived Json via POST /collection/TABLE_NAME

You can change the storage and collection name within url and json.

Testcase: * testGetAttributesAndCreateTable()

Function 11: Create a collection with forign keys

URL:

Method: POST

Body: Attribute definitions with forign key attributes

Additional attributes for references:

Name Description Possible Values Default value Optional
refCollection Referenced collections name any collection name - false
refAttribute Referenced attributes name any attribute name - false
refName References name varchar db-system generated true
refStorage Referenced storage name any storage name - true
refOnDelete CASCADE - true
refOnUpdate CASCADE - true
  1. Send POST request
    • Collection is created with refernces

Exception:

  1. Referenced attribute / collection / storage does not exists.
  • Error message
  • Response state: 500 INTERNAL SERVER ERROR (subject to change)

Function 12: Abfragen der Fremdschlüssel einer Collection

  1. Es sollen die Fremdschlüssel einer Collection aufgelistet werden
    • Es muss eine Collection, die Fremdschlüssel kennt abgefragt werden
    • In der Auflistung der Attribute werden mit refName, refStorage, refAttribute, refOnUpdate, refOnDelete die Eigenschaften des Fremdschlüssels ausgegeben

Ausnahmen: Es werden dieselben Ausnahmen angewendet, wie beim Abfragen von Collections ohne Fremdschlüssel

Beispiel Antwort:

  "name": "tbl_file_join_oo",
  "attributes": [
    {
      "isAutoIncrement": false,
      "refCollection": "tbl_observedobject",
      "refOnDelete": "CASCADE",
      "isNullable": true,
      "name": "oo_id",
      "isIdentity": false,
      "refAttribute": "id",
      "type": "int8",
      "refName": "tbl_file_join_oo_fk",
      "refStorage": "smartmonitoring",
      "refOnUpdate": "CASCADE"
    },
    ...

Function 13: Abfragen aller Referenzen zu und von einer Collection

Fragt die Referenzen von und zu einer Collection ab und listet sie auf.

Beispiel: https://scl.fh-bielefeld.de/SmartDataAirquality/smartdata/collection/tbl_observedobject/references?storage=smartmonitoring

Antwort:

{"references": [
    {
       "from_storage" : "smartmonitoring",
       "from_collection" : "schemes_visuals",
       "from_attr" : "observedobject_id",
       "to_storage" : "smartmonitoring",
       "to_collection" : "tbl_observedobject",
       "to_attr" : "id"
    }, {
       "from_storage" : "smartmonitoring",
       "from_collection" : "schemes_activity",
       "from_attr" : "observedobject_id",
       "to_storage" : "smartmonitoring",
       "to_collection" : "tbl_observedobject",
       "to_attr" : "id"
    }, {
       "from_storage" : "smartmonitoring",
       "from_collection" : "tbl_location_join_oo",
       "from_attr" : "oo_id",
       "to_storage" : "smartmonitoring",
       "to_collection" : "tbl_observedobject",
       "to_attr" : "id"
    }, {
       "from_storage" : "smartmonitoring",
       "from_collection" : "tbl_observedobject",
       "from_attr" : "parent_id",
       "to_storage" : "smartmonitoring",
       "to_collection" : "tbl_observedobject",
       "to_attr" : "id"
    }
  ],
  "name": "tbl_observedobject",
  "storage": "smartmonitoring"
}

Clone this wiki locally