Queries

Data in the repository of an ADOXX-based product is stored in the form of models, objects, relations and attributes. This document explains how this data within a repository can be searched and analysed using a powerful query language.

Specification

When running a search against the contents of the repository, the rules for this search are formulated as a query JSON object. This query object is e.g. used as parameter for the Search REST endpoint. The query object supports the following properties:

• bigDataMode (boolean): An optional parameter that allows to fetch more than the configured (default 10000) amount of search results. Default: false
• attributes (array): An optional list of the attribute names that should be fetched for each result element. If this is not present or if an empty array is passed, then all attributes (except for record attributes) will be contained for each result element.
• relations (array): An optional list of the relation class names of relations that should be fetched for each result element. If this is not present, no relations will be fetched. If this is passed as empty array, all relations will be fetched.
• union (array): An array of objects comprising of filters array, for which the result lists will be joined and returned ( this will return all entries found by any of the filters ). Can be nested.
• intersect (array): An array of objects comprising of filters array, for which the result lists will be intersected and returned (this will return only the entries found by all of the filters). Can be nested.
• diff (array): An array of objects comprising of filters array, for which the result set will be a difference of the provided sub query definitions. Can be nested.
• scope (object): The scope for which the query should be executed. This defines which types of elements will be found (by default, only repository objects are found). Possible contained keys could be:
  • models (boolean): If this is true, models will be found.
  • repoObjects (boolean): If this is true, repository objects will be found.
  • modObjects (boolean): If this is true, modelling objects will be found.
  • repo (boolean): If this is true, all the items in the repository are considered. Please use this option with care as the entire repository will be used for searching.
  • groups (object): Note: If this is set, then the other scope parameters ( models, repoObjects, modObjects, repo ) are ignored! This is a configuration object with which the groups from which data should be retrieved can be defined. The following properties are supported:
    • objectGroups (array): An array of object group paths, e.g. ["Objects/test", "Objects/group1/subgroup"].
    • modelGroups (array): An array of model group paths, e.g. ["Models/test", "Models/group1/subgroup"].
    • includeSubGroups (boolean): An optional boolean property controlling whether the contents of subgroups of the specified groups should be considered. Default: true.
    • useGroupsAsFilter (boolean): An optional boolean property controlling whether the passed groups should be used as filter of the result (if not, the groups are used as starting points). Default: false.
  • objects (array): array of objects, if not querying the whole catalogue then query objects can be provided explicitly via this parameter. Must be a collection of repository artefacts . The contained keys are:
    • objID (string): mandatory, the id of the repository artefact
    • type (number): mandatory, the type of the artefact, one of the following: 0 (for repository objects), 1 (for models) or 6 (for modelling objects)
    • modelID (string): optional, mandatory only if the type is 6 (for modelling objects)
    • libObjID (string): optional, mandatory only if the type is 6 (for modelling objects)
    • repObjID (string): optional, could be given only if the type is 6 (for modelling objects)
• omitRecords (boolean): allows to omit all the record attributes from the result. Defaults to false.
• omitBrokenRelations (boolean): allows to exclude all broken relations from the result. Defaults to false.
• omitInvisibleRelations (boolean): if omitRelations is false then it allows to exclude all invisible relations from the result. Default false.
• sourceQueryID (string): it allows to start query from the result of another cached query ( identified by the provided query ID ). In this case no query scope object should be provided, just the ID of the previously executed query.
• filters (array): An array of filters that can be defined for the query, currently supported filters are: Filter by class name: The following properties are required:
  • className (string/array): The name of the class to filter for. It can also be an array of class names, in this case instances of all listed classes are considered. Filter by attribute value: The following properties are required:
  • attrName (string): The name of the attribute to filter by
  • value (variant): The value to match, type depends on the attribute type ( integer, boolean, string etc. ).
  • values (array): An array of values to match, type depends on the attribute type ( integer, boolean, string etc. ).
  • op (string): The operator for the comparison of attribute and reference value. The following operators are supported ( by default OP_EQ operator is used ):
    • OP_EQ: The values have to be equal.
    • OP_EQUALS: The values have to be equal ( similar to "OP_EQ" ).
    • OP_NEQ: The values have to be not equal.
    • OP_LIKE: The values have to be similar.
    • OP_NLIKE: The values have to be not similar.
    • OP_REGEX: The value of the attribute has to match the regular expression specified in the value. It follows the Perl regular expression syntax ( for example: http://www.boost.org/doc/libs/1_54_0/libs/regex/doc/html/boost_regex/syntax/perl_syntax.html ).
    • OP_EMPTY: checks for empty value (in this case, no value or values property is required for the filter).
    • OP_CONTAINS_ANY: perform equal match on the provided values using OR operator, so just one of the user values must match. Relevant for ENUM like attributes.
    • OP_GR: greater than ( > ), the attribute value is the left-side argument for the operator.
    • OP_GR_EQ: greater or equal (>=), the attribute value is the left-side argument for the operator.
    • OP_LE: less (<), the attribute value is the left-side argument for the operator.
    • OP_LE_EQ: less or equal (<=), the attribute value is the left-side argument for the operator.
    • OP_MATCH_ALL: can be used with the attribute filter. Matches all objects where the value for given attribute is set. Differs from OP_NEMPTY when handling "no value" attributes. OP_MATCH_ALL will match both set values and no values for attributes that support "no value" whereas OP_NEMPTY operator will not return objects where no value is set (in this case, no value or values property is required for the filter).
    • OP_NEMPTY: checks for not empty value (in this case, no value or values property is required for the filter).
    • OP_NRANGE: checks if value is not in the provided range: [LowerRange, UpperRange]. The interval is considered left-closed and right-closed.
    • OP_RANGE: checks if value is in the provided range: [LowerRange, UpperRange]. The interval is considered left-closed and right-closed.
  • logOp (string): A logical operator to be used in case multiple values are passed. Can be OR (logical OR, the value has to match one of the passed values using the defined operator) or AND (logical AND, the value has to match all of the passed values using the defined operator). Default: OR
  • phrasalSearch (boolean): Either true or false (default). If this is set to true, phrasal search will be applied when using relevant operator such as the "OP_LIKE" operator.
  • attrID (string): can only be used if single "attrName" is provided. This specializes the query as "attrName" is not necessarily unique inside the library.
  • relName (string): sets up the relation filter. Allows to search for objects that have relations to specific objects (identified by the objects' name). Needs to be combined with op and value or values
  • caseInsensitive (boolean): can only be used with operator "OP_EQ" to provide case insensitive comparison, by default it is false.
  • checkOwnerModel (boolean): allowed only for simple values. The check is then executed for the owner model for all modelling instances in the current set.
  • checkCondition (object): allowed only for simple values. Special conditions under which the check should be executed. Contains following keys:
    • className (array): name of the classes for which the check should be executed. The classes outside of this collection will not be checked and automatically added to the current result.
  • columns (array): when attrName is a record it can be used by the user to look up for a value at a specific column, specifying also a comparison operator. To specify the query for a column a dictionary-like parameter object is used with the keys: name (language independent column name, string type ), value and op (like shown in the example below ). E.g. filter({attrName: "..", columns : [{name: "..", value: "..", op: "OP.."}]}) When used with multiple columns it considers values in the same row. It uses the logical operator input by the parameter "columnsOp" for multiple columns.
  • columnsOp (string): defined logical operators to connect the sub queries defined in "columns", can be one of the following:
    • COL_OP_AND: AND logical operator to connect subqueries.
    • COL_OP_OR: OR logical operator to connect subqueries.
  • incoming (boolean): relevant only if relName is used. If set to true then incoming relations will be filtered, defaults to false.
  • outgoing (boolean): relevant only if relName is used. If set to true then outgoing relations will be filtered, defaults to opposite of incoming flag.
  • targetClassName (array): array of strings - relevant only if relName is used. If a relation class can have multiple target classes then this filter allows to restrict result to a subset.
  • excluding (boolean): relevant only if className is used. If set to true then the classes contained in the className value will be excluded from the result, defaults to false.
  • langSpecValues (boolean): relevant only if attrName is used and the type of attribute is ENUM / ENUMLIST / ENUMLIST_TREE. If this is true then language specific values (or parts of values) can be passed to the query. Defaults to false ( query API expects language independent values like v0, v1 etc. )
• recursive (boolean): Default: false. Define it true if recursion at chain level is desired.
• omitRecords (boolean): allows to omit all the record attributes from the result. Defaults to false.
• omitChangeHistory (boolean): allows to omit all the change history records from theresult. Defaults to false.
• omitRelations (boolean): allows to omit all the relations from the result. Defaults to false.
• omitBrokenRelations (boolean): allows to exclude all broken relations from the result. Defaults to false.
• omitInvisibleRelations (boolean): if omitRelations is false then it allows to exclude all invisible relations from the result. Default false.
• sourceQueryID (string): it allows to start query from the result of another cached query ( identified by the provided query ID ). In this case no query scope object should be provided, just the ID of the previously executed query.
• navigate (object): This allows navigating based on the current intermediate result and taking the result directly or executing subsequent queries on it.
  • type (string): This defines what type of navigation should be used. The following types are available:
    • QUERY: The default option if no other option is set, this allows e.g. to execute a subsequent query on a union result with the query parameter.
    • CONTENT: Navigates to the modelling objects within a model. This requires following parameters:
      • className (string/array): the modelling instance class names that should be retrieved. If null then all the modelling instances will be added. Note: this is skipping all the connectors (relations).
    • REPO_OBJECT: Navigates to the repository objects of modelling objects.
    • MOD_OBJECT: Navigates to the modelling objects of repository objects.
    • MODEL: Navigates to the model(s) in which the current set of objects is contained.
    • REF_MODELS: If the current filter queries for repository instances then we go to the models where they are referenced ( there are modelling instances - at least one - based on given repository instance ). This requires following parameters:
      • className (array/string): Optional, the model class names that should be retrieved. If null then all the referenced models will be added.
    • REF_REPOINSTS: If the current filter queries for models then we go to directly to the repository instances being referenced in them. This requires following parameters:
      • className (array/string): Optional, the repository instance class names that should be retrieved. If null then all the repository instances will be added. This is skipping all the connectors (relations).
    • FOLLOW: Navigates to the target of the relation class passed in parameters. This type requires the following parameters:
      • className (array): array of strings - the relation classes that should be followed. If null or empty then all the relations will be considered.
      • targetClassName (array): array of strings - if a relation class can have multiple target classes then this filter allows to restrict result to a subset.
      • incoming (boolean): if set to true then incoming relations will be followed, defaults to false.
      • outgoing (boolean): if set to true then outgoing relations will be followed.
      • skipBrokenEp (boolean): if set to true then broken endpoints will be skipped during the follow, defaults to false.
      • targetType (string): the followed target type of the filter which should be contained in the result set. One of the string constants beginning with "FOLLOW_*". Defaults to FOLLOW_TRG_OBJ if the relation is outgoing or FOLLOW_SRC_OBJ if the relation is incoming. Possible options are:
        • FOLLOW_SRC_OBJ: target type is source object.
        • FOLLOW_TRG_OBJ: target type is target object.
      • recursive (boolean): if set to true relation(s) will be followed recursively while there are available connections according to the config, defaults to false. For now this is allowed only if at least one of incoming/outgoing is not set to true.
      • addIntermediateResult (boolean): relevant only if recursive is true. If it is also true then intermediate result from all recursions will be added to the final result set, if false then only result of the last successful recursion will be persisted. Defaults to false.
  • parameters (object): A map of key-value pairs that is required for some navigate types (e.g. FOLLOW, CONTENT, QUERY etc. ).
  • query: A subsequent query on the current result. The query itself can again contain a filters section and/or a navigate option.

Examples

Use case	Query	Expected result
Filtering by attribute	{ "filters": [ { "attrName": "NAME", "op": "OP_LIKE", "value": "app" } ], "scope": { "repoObjects": true, "models": true, "modObjects": true } }	Find all the artefacts (repository object, modelling instances and models) where the attribute "NAME" contains (using operator "LIKE") "app".
Filtering by class	{ "filters": [ { "className": "C_APPLICATION" } ], "scope": { "repoObjects": true } }	Find all repository objects of class "C_APPLICATION".
Follow a relation	{ "filters": [ { "className": "C_SERVICE" } ], "navigate": { "query": { "navigate": { "parameters": { "className": "RC_IS_APPLICATION_OWNER", "outgoing": true }, "type": "FOLLOW" } }, "parameters": { "className": "RC_IS_DEPENDENT_ON", "outgoing": true }, "type": "FOLLOW" }, "scope": { "repoObjects": true } }	Follow the outgoing relation "RC_IS_DEPENDENT_ON" for the repository artefacts of class type "C_SERVICE". Then on the result set of the first follow, another follow filter is applied with the outgoing relation "RC_IS_APPLICATION_OWNER". The result set contains the target artefacts.
Combination of class and attribute filter	{ "filters": [ { "className": "C_TASK" }, { "attrName": "NAME", "op": "OP_LIKE", "value": "Social" } ], "scope": { "repo": true } }	Find all the "C_TASK" artefacts in the entire repository where the "NAME" attribute contains (using the "OP_LIKE" operator) "Social".
Union	{ "union": [ { "filters": [ { "attrName": "NAME", "op": "OP_LIKE", "value": "one" } ] }, { "filters": [ { "attrName": "NAME", "op": "OP_LIKE", "value": "two" } ] } ], "scope": { "modObjects": true } }	Find all the modelling objects where the "NAME" attribute contains "one" or "two".
Intersect	{ "intersect": [ { "filters": [ { "className": "C_APPLICATION" } ] }, { "filters": [ { "attrName": "NAME", "op": "OP_LIKE", "value": "Social" } ] } ], "scope": { "repoObjects": true } }	Find all artefacts of class "C_APPLICATION" where the "NAME" attribute contains "Social".