Index and queries
ShareAspace supports a query engine that can be used to access instances of SoftTypes, i.e. the data held.
Introduction
With the query engine it is possible to define queries based on the SoftType definitions. These query definitions are available in the API as well as in the user interface. Queries can be defined to be executed without the need of user input as well as defined as requiring user input. "All documents created by me" could be a typical query that executes with input based on who triggered the query and not asking for any user input, while a "Document with name" could be a query requiring the user to give a query parameter for a document name string.
Queries can be defined for a specific SoftType, be defined for a set of SoftTypes, or even be defined for a SoftType and its relations to other SoftTypes.
The defined queries can also be configured and saved as personal queries where a user might want to repeatedly use the same query without having to type in the same input data over and over again. The user also has the possibility to define what result attributes should be presented in the query result, picking from a set of defined result attributes.
How it works
Based on system metadata attributes and attributes defined in the SoftType output schema a query index can be created. This index can then be used to apply query logic and result selection.
The query definitions can be setup in the Project Template or be added to a project at runtime.
It is also possible for end users to create personal queries, either from scratch or by copying an already existing query.
Index grouping
Index grouping allows for grouping values that belong together in an index. This in turn allows for more advanced queries to be defined.
To explain this in more detail, let's use a simple example.
Say we have a Part that has an array of identifiers. Each identifier has a text value for the id itself. Each identifier also has a context reference stating what organization it is that is using a particular id value. This allows for different organizations who identify the same part with their own specific identifiers.
| id | context |
|---|---|
| 123 | Organization-A |
| ABC | Organization-B |
With the index grouping the value pairs can be kept together, which makes it possible to do the more specific query operations.
If you would just search for all parts (let's say there is only one in the system) you can by configuration define if you want one hit for each possible combination, or if you want to concatenate the rows.
All parts:
| ids.id | ids.contexts | Name |
|---|---|---|
| 123 | Organization-A | Part 1 |
| ABC | Organization-B | Part 1 |
Note
That both hits refer to the same part.
If you were to search using "ids.id" = 123 you would get the matching result: |ids.id |ids.contexts |Name | |-------|---------------|-------| |123 |Organization-A |Part 1 |
And if you are more explicit, like ids.id = 123 AND ids.context = Organization-B you would get no hits since the id value of 123 belongs to Organization-A.
Index history
With index history it is possible to index the full history of a reference. All effectivity controlled references like property values can be indexed.
E.g. the history support functionality makes it possible to define queries like "find all parts that ever had the price of 10 USD". (Compared to "find all parts that currently have the price of 10 USD".)
Limitations
There are a couple of things to consider when configuring indexes to be used by queries.
Truncation
When indexing string values there is a limit in the number of characters that will be indexed. When passing the limit, the index will truncate the value. Note that the truncation only happens in the index. The data within the Unit of Information will be kept.
Note
Indexes will truncate string values at 2000 bytes. What this means in numbers of characters depends on what characters are used in the string. Using Aa-Zz, 0-9, and space, this would be 2000 characters. A special character can however use 2-3 bytes.
Tip
To be sure to avoid truncated index values consider limiting your string values to ~650 characters (2000/3 rounded down).
Caution
The truncation of strings only applies to the indexes. There is no limit to the number of characters that ShareAspace can store on string values in the database. Storing large strings on the string values will however affect the payload size when requesting data from ShareAspace.
There is one exception to this truncation, when indexing strings stored on Descriptor
entries there is another form of truncation when compared with string values stored on
entries like Name and StringPropertyValue. When indexing string values on Descriptor the strings are split on the space
character. Each split sub string is then truncated at 2000 bytes.
Because of this there are also two behaviors when querying strings stored on
Descriptor, compared to all other string values.
While most strings can be operated on using operators like, "Starts With", "Ends With",
"Contains", "Like", "Equals". The Descriptor query will do this operator for each split
string within the Descriptor string value.
Number of indexes and index size
Another thing to consider is the number of indexes configured and the number of objects within each index. The number of indexes and the volume of data within the indexes will have an impact on indexing and especially when rebuilding the indexes. Running spaces with many and large indexes will require a "stronger" server environment. I.e. it will impact the hosting hardware pre-requisites.
Indexing references
It is possible to index values over SoftType references, e.g. when indexing a "Document" SoftType with a reference to a "Classification" SoftType. In the "Document Index" it is possible to have an index term "Classified As", where "Classified As" could be the id of the Classification SoftType referenced by the Document (like Document.Class.Id).
The indexing limit here comes at the reference. It is only possible to "walk" over one reference when indexing. In the "Document Index" exemplified above, it would not be possible to index values from a SoftType referenced by the Classification.
Defining queries
How to define queries in the Project Template is described in the configuration section.
How to use queries from the user interface is described in the User Guide.