This example tutorial provides explanations and code examples to get an idea on how to define and specify structured data properties and on how to query them.
Introduction
yuuvis® Momentum offers a property type for the storage of structured data in JSON format. Thus, it is possible to store interleaved data structures in a queryable way without defining each single sub-property in the schema. The structured data properties should NOT be considered to replace the concept of a well-defined schema. They should be used only if the handling of objects' metadata via the conventional property definitions is not reasonable. Especially, if the structure of metadata and/or the availability of properties differs a lot for the individual object instances, the schema might grow up to a really long list of scarcely used properties. This can be avoided by the usage of a property field that can store a JSON structure as value. In this tutorial, the registration information of media in a library is considered an example use case. For this purpose, the set of information for each medium is provided in JSON structure following the concept of BibJSON.
Requirements
This tutorial is dedicated to experienced users. Please find information on requirements, maven and client configuration in our "Importing Documents via Core API" tutorial, on which the variables' names are based. The handling of any IOException is demonstrated there, too.
Definition in the Schema
In the context of the library example, the below displayed app schema is used that contains two property definitions and one object type definition referencing the properties. The first property bibjsonsample:bibjson has the property type structureddata. This property will be used for the storage of the BibJSON structure containing the registration information of the corresponding medium. The second property bibjsonsample:locations allows for the assignment of a list of strings indicating storage locations if a printed version is available for the corresponding medium. In the object type definition of bibjsonsample:medium, both properties are referenced. Additionally, a binary content file can be assigned if necessary.
<?xml version="1.0" encoding="utf-8"?>
<schema xmlns="http://optimal-systems.org/ns/dmscloud/schema/v5.0/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://optimal-systems.org/ns/dmscloud/schema/v5.0/ dmsCloud-schema.xsd">
<propertyStructuredDataDefinition>
<id>bibjsonsample:bibjson</id>
<description>field for the BibJSON structure identifying and describing the medium</description>
<propertyType>structureddata</propertyType>
<cardinality>single</cardinality>
<required>false</required>
</propertyStructuredDataDefinition>
<propertyStringDefinition>
<id>bibjsonsample:locations</id>
<description>field for storage locations of printed versions of the medium</description>
<propertyType>string</propertyType>
<cardinality>multi</cardinality>
<required>false</required>
</propertyStringDefinition>
<typeDocumentDefinition>
<id>bibjsonsample:medium</id>
<baseId>system:document</baseId>
<propertyReference>bibjsonsample:bibjson</propertyReference>
<propertyReference>bibjsonsample:locations</propertyReference>
<contentStreamAllowed>allowed</contentStreamAllowed>
</typeDocumentDefinition>
</schema>
Specify Values during Import
Two example objects will be created as instances of the object type abbBibjsonsample:medium. Both of them get a BibJSON value for the property appbibjsonsample:bibjson assigned to them. For the individual sub-values, the system can identify integers, booleans and datetime of format yyyy-MM-ddTHH:mm:ss.xxxZ. All other values are set to strings.
The first object is a book. In addition to the bibliographic information stored in the property appbibjsonsample:bibjson, two storage locations for printed versions are specified.
{
"objects": [{
"properties": {
"objectTypeId": {
"value": "appBibjsonsample:medium"
},
"appBibjsonsample:bibjson": {
"value": {
"type": "book",
"title": "My Book Title",
"author": [
{"name": "Heinrich Schuetzel"},
{"name": "Maximilian Sturz"}
],
"year": "1995",
"owner": "My Library",
"id": "ID_of_book",
"url": "http://mylibrary.com/ebooks/36513466534",
"publisher": "Example Verlag Mustershagen",
"edition": {
"number": 2,
"language": "English"
},
"identifier":[
{
"id": "0002-9327",
"type": "issn"
}
]
}
},
"appBibjsonsample:locations": {
"value": [
"central library, CN-3214-5324",
"branch library east, 43-654b"
]
}
}
}]
}
The second object is a collection of articles without corresponding printed versions.
{
"objects": [{
"properties": {
"objectTypeId": {
"value": "appBibjsonsample:medium"
},
"appBibjsonsample:bibjson": {
"value": {
"metadata": {
"collection": "ym_concepts",
"label": "yuuvis(R) Momentum Core Concepts",
"description": "Documentation for yuuvis(R) Momentum Core in a structured, theoretical way, with links to the tutorial section.",
"id": "ID_of_collection",
"owner": "OS",
"created": "2020-06-09T15:04:12.944Z",
"modified": "2021-06-10T11:05:17.166Z",
"source": "https://help.optimal-systems.com/yuuvis_develop/display/YMY/x/-4BkAg",
"records": 2
},
"records": [
{
"collection": "ym_concepts",
"type": "article",
"title": "Schema - Defining Object Types",
"id": "ID_of_schema_article",
"link": "https://help.optimal-systems.com/yuuvis_develop/display/YMY/x/AYFkAg",
"author":[
{"name": "Heinrich Schuetzel"},
{"name": "George Trader"},
{"name": "Johann Fluss"}
],
"created": "2020-06-09T15:04:12.944Z",
"modified": "2021-06-10T08:53:23.532Z"
},
{
"collection": "ym_concepts",
"type": "article",
"title": "Search Query Language",
"id": "ID_of_query_article",
"link": "https://help.optimal-systems.com/yuuvis_develop/display/YMY/x/gIFkAg",
"author":[
{"name": "Andrea Schumann"},
{"name": "Franz Lissner"},
{"name": "Hans Kammer"},
{"name": "Johann Fluss"}
],
"created": "2020-06-16T14:03:01.833Z",
"modified": "2021-06-02T09:54:12.643Z"
}
]
}
}
}
}]
}
The successfully executed import returns the entire sets of metadata for each object, enriched with the system properties.
{
"objects": [
{
"properties": {
"system:objectId": {
"value": "aab2b4d9-e829-45dd-981a-2f19a688592d"
},
"system:baseTypeId": {
"value": "system:document"
},
"system:objectTypeId": {
"value": "appBibjsonsample:medium"
},
"system:createdBy": {
"value": "275c826c-6a61-4e89-9512-8d935a1631e5"
},
"system:creationDate": {
"value": "2021-06-14T13:10:52.280Z"
},
"system:lastModifiedBy": {
"value": "275c826c-6a61-4e89-9512-8d935a1631e5"
},
"system:lastModificationDate": {
"value": "2021-06-14T13:10:52.280Z"
},
"system:versionNumber": {
"value": 1
},
"system:tenant": {
"value": "default"
},
"system:traceId": {
"value": "5681d3bddb4279de"
},
"appBibjsonsample:bibjson": {
"value": {
"type": "book",
"title": "My Book Title",
"author": [
{
"name": "Heinrich Schuetzel"
},
{
"name": "Maximilian Sturz"
}
],
"year": "1995",
"owner": "My Library",
"id": "ID_of_book",
"url": "http://mylibrary.com/ebooks/36513466534",
"publisher": "Example Verlag Mustershagen",
"edition": {
"number": 2,
"language": "English"
},
"identifier": [
{
"id": "0002-9327",
"type": "issn"
}
]
}
},
"appBibjsonsample:locations": {
"value": [
"central library, CN-3214-5324",
"branch library east, 43-654b"
]
}
}
}
]
}
{
"objects": [
{
"properties": {
"system:objectId": {
"value": "3d4a67be-3341-4317-bb57-c48ea7ab0a1a"
},
"system:baseTypeId": {
"value": "system:document"
},
"system:objectTypeId": {
"value": "appBibjsonsample:medium"
},
"system:createdBy": {
"value": "275c826c-6a61-4e89-9512-8d935a1631e5"
},
"system:creationDate": {
"value": "2021-06-14T13:11:57.770Z"
},
"system:lastModifiedBy": {
"value": "275c826c-6a61-4e89-9512-8d935a1631e5"
},
"system:lastModificationDate": {
"value": "2021-06-14T13:11:57.770Z"
},
"system:versionNumber": {
"value": 1
},
"system:tenant": {
"value": "default"
},
"system:traceId": {
"value": "22839c5775801e9c"
},
"appBibjsonsample:bibjson": {
"value": {
"metadata": {
"collection": "ym_concepts",
"label": "yuuvis(R) Momentum Core Concepts",
"description": "Documentation for yuuvis(R) Momentum Core in a structured, theoretical way, with links to the tutorial section.",
"id": "ID_of_collection",
"owner": "OS",
"created": "2020-06-09T15:04:12.944Z",
"modified": "2021-06-10T11:05:17.166Z",
"source": "https://help.optimal-systems.com/yuuvis_develop/display/YMY/x/-4BkAg",
"records": 2
},
"records": [
{
"collection": "ym_concepts",
"type": "article",
"title": "Schema - Defining Object Types",
"id": "ID_of_schema_article",
"link": "https://help.optimal-systems.com/yuuvis_develop/display/YMY/x/AYFkAg",
"author": [
{
"name": "Heinrich Schuetzel"
},
{
"name": "George Trader"
},
{
"name": "Johann Fluss"
}
],
"created": "2020-06-09T15:04:12.944Z",
"modified": "2021-06-10T08:53:23.532Z"
},
{
"collection": "ym_concepts",
"type": "article",
"title": "Search Query Language",
"id": "ID_of_query_article",
"link": "https://help.optimal-systems.com/yuuvis_develop/display/YMY/x/gIFkAg",
"author": [
{
"name": "Andrea Schumann"
},
{
"name": "Franz Lissner"
},
{
"name": "Hans Kammer"
},
{
"name": "Johann Fluss"
}
],
"created": "2020-06-16T14:03:01.833Z",
"modified": "2021-06-02T09:54:12.643Z"
}
]
}
}
}
}
]
}
Search Queries
The individual sub-fields within the JSON value for the property appBibjsonsample:bibjson are queryable. In this chapter, some example search queries are explained.
All objects of type medium.
SELECT * FROM appBibjsonsample:medium
{
"objects": [
{
"properties": {
"system:traceId": {
"value": "5681d3bddb4279de"
},
"system:objectTypeId": {
"value": "appBibjsonsample:medium"
},
"appBibjsonsample:bibjson": {
"value": {
"type": "book",
"title": "My Book Title",
"author": [
{
"name": "Heinrich Schuetzel"
},
{
"name": "Maximilian Sturz"
}
],
"year": "1995",
"owner": "My Library",
"id": "ID_of_book",
"url": "http://mylibrary.com/ebooks/36513466534",
"publisher": "Example Verlag Mustershagen",
"edition": {
"number": 2,
"language": "English"
},
"identifier": [
{
"id": "0002-9327",
"type": "issn"
}
]
}
},
"system:versionNumber": {
"value": 1
},
"system:createdBy": {
"value": "275c826c-6a61-4e89-9512-8d935a1631e5"
},
"system:creationDate": {
"value": "2021-06-14T13:10:52.280Z"
},
"system:lastModificationDate": {
"value": "2021-06-14T13:10:52.280Z"
},
"system:baseTypeId": {
"value": "system:document"
},
"system:tenant": {
"value": "default"
},
"appBibjsonsample:locations": {
"value": [
"central library, CN-3214-5324",
"branch library east, 43-654b"
]
},
"system:lastModifiedBy": {
"value": "275c826c-6a61-4e89-9512-8d935a1631e5"
},
"system:objectId": {
"value": "aab2b4d9-e829-45dd-981a-2f19a688592d"
}
}
},
{
"properties": {
"system:traceId": {
"value": "22839c5775801e9c"
},
"system:objectTypeId": {
"value": "appBibjsonsample:medium"
},
"appBibjsonsample:bibjson": {
"value": {
"metadata": {
"collection": "ym_concepts",
"label": "yuuvis(R) Momentum Core Concepts",
"description": "Documentation for yuuvis(R) Momentum Core in a structured, theoretical way, with links to the tutorial section.",
"id": "ID_of_collection",
"owner": "OS",
"created": "2020-06-09T15:04:12.944Z",
"modified": "2021-06-10T11:05:17.166Z",
"source": "https://help.optimal-systems.com/yuuvis_develop/display/YMY/x/-4BkAg",
"records": 2
},
"records": [
{
"collection": "ym_concepts",
"type": "article",
"title": "Schema - Defining Object Types",
"id": "ID_of_schema_article",
"link": "https://help.optimal-systems.com/yuuvis_develop/display/YMY/x/AYFkAg",
"author": [
{
"name": "Heinrich Schuetzel"
},
{
"name": "George Trader"
},
{
"name": "Johann Fluss"
}
],
"created": "2020-06-09T15:04:12.944Z",
"modified": "2021-06-10T08:53:23.532Z"
},
{
"collection": "ym_concepts",
"type": "article",
"title": "Search Query Language",
"id": "ID_of_query_article",
"link": "https://help.optimal-systems.com/yuuvis_develop/display/YMY/x/gIFkAg",
"author": [
{
"name": "Andrea Schumann"
},
{
"name": "Franz Lissner"
},
{
"name": "Hans Kammer"
},
{
"name": "Johann Fluss"
}
],
"created": "2020-06-16T14:03:01.833Z",
"modified": "2021-06-02T09:54:12.643Z"
}
]
}
},
"system:lastModificationDate": {
"value": "2021-06-14T13:11:57.770Z"
},
"system:versionNumber": {
"value": 1
},
"system:baseTypeId": {
"value": "system:document"
},
"system:tenant": {
"value": "default"
},
"system:createdBy": {
"value": "275c826c-6a61-4e89-9512-8d935a1631e5"
},
"system:creationDate": {
"value": "2021-06-14T13:11:57.770Z"
},
"system:lastModifiedBy": {
"value": "275c826c-6a61-4e89-9512-8d935a1631e5"
},
"system:objectId": {
"value": "3d4a67be-3341-4317-bb57-c48ea7ab0a1a"
}
}
}
],
"numItems": 2,
"hasMoreItems": false,
"totalNumItems": 2
}
Return only the bibjson value
SELECT appBibjsonsample:bibjson FROM appBibjsonsample:medium
{
"objects": [
{
"properties": {
"appBibjsonsample:bibjson": {
"value": {
"type": "book",
"title": "My Book Title",
"author": [
{
"name": "Heinrich Schuetzel"
},
{
"name": "Maximilian Sturz"
}
],
"year": "1995",
"owner": "My Library",
"id": "ID_of_book",
"url": "http://mylibrary.com/ebooks/36513466534",
"publisher": "Example Verlag Mustershagen",
"edition": {
"number": 2,
"language": "English"
},
"identifier": [
{
"id": "0002-9327",
"type": "issn"
}
]
}
}
}
},
{
"properties": {
"appBibjsonsample:bibjson": {
"value": {
"metadata": {
"collection": "ym_concepts",
"label": "yuuvis(R) Momentum Core Concepts",
"description": "Documentation for yuuvis(R) Momentum Core in a structured, theoretical way, with links to the tutorial section.",
"id": "ID_of_collection",
"owner": "OS",
"created": "2020-06-09T15:04:12.944Z",
"modified": "2021-06-10T11:05:17.166Z",
"source": "https://help.optimal-systems.com/yuuvis_develop/display/YMY/x/-4BkAg",
"records": 2
},
"records": [
{
"collection": "ym_concepts",
"type": "article",
"title": "Schema - Defining Object Types",
"id": "ID_of_schema_article",
"link": "https://help.optimal-systems.com/yuuvis_develop/display/YMY/x/AYFkAg",
"author": [
{
"name": "Heinrich Schuetzel"
},
{
"name": "George Trader"
},
{
"name": "Johann Fluss"
}
],
"created": "2020-06-09T15:04:12.944Z",
"modified": "2021-06-10T08:53:23.532Z"
},
{
"collection": "ym_concepts",
"type": "article",
"title": "Search Query Language",
"id": "ID_of_query_article",
"link": "https://help.optimal-systems.com/yuuvis_develop/display/YMY/x/gIFkAg",
"author": [
{
"name": "Andrea Schumann"
},
{
"name": "Franz Lissner"
},
{
"name": "Hans Kammer"
},
{
"name": "Johann Fluss"
}
],
"created": "2020-06-16T14:03:01.833Z",
"modified": "2021-06-02T09:54:12.643Z"
}
]
}
}
}
}
],
"numItems": 2,
"hasMoreItems": false,
"totalNumItems": 2
}
Return only parts of the bibjson value
SELECT appBibjsonsample:bibjson.title,appBibjsonsample:bibjson.author[1].name,appBibjsonsample:bibjson.metadata.id FROM appBibjsonsample:medium
{
"objects": [
{
"properties": {
"appBibjsonsample:bibjson": {
"value": {
"title": "My Book Title",
"author": [
null,
{
"name": "Maximilian Sturz"
}
]
}
}
}
},
{
"properties": {
"appBibjsonsample:bibjson": {
"value": {
"metadata": {
"id": "ID_of_collection"
}
}
}
}
}
],
"numItems": 2,
"hasMoreItems": false,
"totalNumItems": 2
}
If the path is unknown, a '*' wildcard can be used.
SELECT appBibjsonsample:bibjson.metadata.id FROM appBibjsonsample:medium WHERE appBibjsonsample:bibjson.* = 'ID_of_schema_article'
{
"objects": [
{
"properties": {
"appBibjsonsample:bibjson": {
"value": {
"metadata": {
"id": "ID_of_collection"
}
}
}
}
}
],
"numItems": 1,
"hasMoreItems": false,
"totalNumItems": 1
}
Search within a list and usage of CONTAINS
SELECT appBibjsonsample:bibjson.title FROM appBibjsonsample:medium WHERE appBibjsonsample:bibjson.author[*].name CONTAINS('Sturz')
{
"objects": [
{
"properties": {
"appBibjsonsample:bibjson": {
"value": {
"title": "My Book Title"
}
}
}
}
],
"numItems": 1,
"hasMoreItems": false,
"totalNumItems": 1
}
Search within the records of collections
SELECT appBibjsonsample:bibjson.records.title,appBibjsonsample:bibjson.metadata.id FROM appBibjsonsample:medium WHERE appBibjsonsample:bibjson.records[*].created IN LASTYEAR()
{
"objects": [
{
"properties": {
"appBibjsonsample:bibjson": {
"value": {
"metadata": {
"id": "ID_of_collection"
}
}
}
}
}
],
"numItems": 1,
"hasMoreItems": false,
"totalNumItems": 1
}
Summary