1. Types
  2. cis
  3. data
  4. resource model

cis data resource model: query spec

A query which encapsulates a request for specific resource model data. It supports filtering the resource model data to return by specifying conditions on the targeted resource model properties as well as retrieval of arbitrary number of properties or sub-properties of the resource models that satisfy the filter criteria. Also, it allows for sorting and limiting the final result set.

Each query has the following main constituents:

  1. Property List: specifies the list of property values to be returned in the result set for the query. Corresponds to the SELECT clause in SQL.
  2. Resource Model List: specifies one or multiple resource models (for the same resource type) that should be queried. Corresponds to the FROM clause in SQL.
  3. Filter: restricts (filters) the set of resource models whose properties should be returned based on conditions/predicates on their property values. Corresponds to the WHERE clause in SQL.
  4. Sort Criteria: defines how the final result set should be sorted by comparing the values of one or more properties of the items in the result set. Corresponds to the ORDER BY clause in SQL.
  5. Page Specification: specifies what portion of the final sorted result set should be returned to the client. Defined by a combination of two fields: #offset and #limit.

Representation:

{
    "resource_models" : [
        "string",
        "string"
    ],
    "filter" : {
        "criteria" : [
            {
                "comparable_value" : "opaque_string_value",
                "property" : "string",
                "comparable_list" : [
                    "opaque_string_value",
                    "opaque_string_value"
                ],
                "operator" : "EQUAL"
            },
            {
                "comparable_value" : "opaque_string_value",
                "property" : "string",
                "comparable_list" : [
                    "opaque_string_value",
                    "opaque_string_value"
                ],
                "operator" : "EQUAL"
            }
        ],
        "operator" : "AND"
    },
    "sort_criteria" : [
        {
            "sort_direction" : "ASCENDING",
            "property" : "string"
        },
        {
            "sort_direction" : "ASCENDING",
            "property" : "string"
        }
    ],
    "offset" : 1,
    "limit" : 1,
    "properties" : [
        "string",
        "string"
    ],
    "return_total_count" : true
}

Attributes:

Name Type Description
Required
properties string[] The names of the (resource model) properties to be included in the result set for the query.

Each property name could be either a single property name, in case of an immediate property of the resource model or a property path, i.e. chain of property names, separated with / symbol to indicate a child property, e.g. relatives/father.

In case a requested property is present in more than one of the queried resource models (specified in cis.data.resource_model.query_spec.resource_models) the property name should be prefixed by the fully-qualified name of the resource model of interest, followed by / symbol before the actual property name, e.g. com.acme.PersonModel/relatives/father.

Corresponds to the SELECT clause in SQL, where the property names correspond to column names.

The list must not be empty. Otherwise, vapi.std.errors.invalid_argument error will be thrown.
resource_models string[] The names of the resource models to be queried. All properties used in the query should belong to one of those resource models. If a property from another model is used somewhere else in the query an vapi.std.errors.invalid_argument error will be thrown to indicate this violation. Multiple resource models could be specified here only if they all belong to the same resource type. In case multiple resoruce models are specified they are implicitly joined on their primary key @modelKey property.

Each resource model name should be fully-qualified, e.g. com.acme.PersonModel

Corresponds to the FROM clause in SQL where the resource models correspond to tables.

The list must not be empty. Otherwise, vapi.std.errors.invalid_argument error will be thrown.
filter.criteria property_predicate[] A set of conditions on the resource model properties that together define the criteria for filtering/matching the resources whose data to retrieve.

The list must not be empty. Otherwise, vapi.std.errors.invalid_argument error will be thrown.
filter.criteria[].property string Specifies the resource model property to be compared.

The property name could be either a single property name, in case of an immediate property of the resource model or a property path, i.e. chain of property names, separated with / symbol to indicate a child property, e.g. relatives/father.

In case the specified property is present in more than one of the queried resource models (specified in cis.data.resource_model.query_spec.resource_models) the property name should be prefixed by the fully-qualified name of the resource model of interest, followed by / symbol before the actual property name, e.g. com.acme.PersonModel/relatives/father.
filter.criteria[].operator string The operator to use for comparison of the property value.

Defines the possible operators to use when comparing the values of individual resource model properties.

When comparing values of different types, one of the values can be promoted from one type to another (if needed in order to perform correct comparison) according to the following rules:

  • When comparing numeric values, a comparable of type long could be promoted (converted) to type double. The result value will be the same as the original value.
  • When comparing to a boolean value, a comparable of type string can be converted to boolean if the value is parsable to boolean, i.e. either false or true in lower case.
Value is one of:
EQUAL: Equality operator
NOT_EQUAL: Inequality operator
GREATER: Greater than operator
GREATER_OR_EQUAL: Greater than or equal to operator
LESS: Less than operator
LESS_OR_EQUAL: Less than or equal to operator
IN: Checks for equality with at least one of a list of values
Optional
filter filter Restricts (filters) the set of resource models whose properties should be returned based on conditions/predicates on their property values.

Corresponds to the WHERE clause in SQL.

Optional. If unset, the query matches all instances of the resource models specified in the cis.data.resource_model.query_spec.resource_models field (FROM clause).
filter.criteria[].comparable_value opaque The primitive value that the property should be compared to. Note that only the following primitive value types could be used for comparison:
  • integer
  • floating point number
  • boolean
  • string
If any other type is provided, vapi.std.errors.invalid_argument exception will be returned.

Please, note that when comparing with resource identifier, i.e. @modelKey property, the comparable value should be of string type.

Optional. It is only relevant when operator has value [EQUAL, NOT_EQUAL, GREATER, GREATER_OR_EQUAL, LESS, LESS_OR_EQUAL]. This field is optional and it is only relevant when the value of operator is one of EQUAL, NOT_EQUAL, GREATER, GREATER_OR_EQUAL, LESS, or LESS_OR_EQUAL.
filter.criteria[].comparable_list opaque[] The list of primitive values to test for equality with the property value when operator IN is used. The list cannot be empty. See cis.data.resource_model.property_predicate.comparable_value for the list of allowable primitive value types.

Optional. It is only relevant when operator has value IN. This field is optional and it is only relevant when the value of operator is IN.
filter.operator string The logical operator which defines how the property predicates should be combined in order to filter a given resource.

Optional. If unset, defaults to AND.
sort_criteria sort_criterion[] Defines how the final result set should be sorted by comparing the values of one or more properties of the items in the result set. Represents a list of one or more sorting criteria, where those with lower indices in the list takes precedence over the specs with higher indices.

Corresponds to the ORDER BY clause in SQL.

Optional. If unset, no sorting will be applied.
offset long The offset into the result set. Must be non-negative number.

If the offset is N then items from N to N + limit - 1 will be returned.

Optional. If unset, resources starting from the very first element will be returned.
limit long The maximum number of result items to return. Could be used only if sorting criteria cis.data.resource_model.query_spec.sort_criteria is applied. If used, the value should be positive integer.

Optional. If unset, all resources will be returned. Note that the service defines its own limit that cannot be overriden here. If the more resources than this default limit, an vapi.std.errors.invalid_argument error will be thrown.
return_total_count boolean Indicates whether the total number of resources that matched the query should be computed and returned. This is meaningful only in cases where the number of resources that match the query could be more than the limit of the result items to be returned as specified in cis.data.resource_model.query_spec.limit, or if the client wants to retrieve only the number of items that matched the query, but without the items themselves. If unset, defaults to false.

The total number of matched resources depends solely on the cis.data.resource_model.query_spec.filter and the cis.data.resource_model.query_spec.resource_models. It does not depend on the requested cis.data.resource_model.query_spec.properties, i.e. the total count is similar to but less expressive than the SQL count function.

NOTE: Use this with particular caution and only when it's absolutely needed as the computation of this value could have noticeable performance overhead.

Optional. If unset, it will be automatically assigned as false.