REST API - query

cis data provider resource model: query

Executes the provided cis.data.provider.resource_model.query_spec instance, i.e. retrieve a snapshot of the resource model data as specified in the query.

Request:

HTTP request

POST https://{server}/rest/com/vmware/cis/data/provider/resource-model?~action=query

Request Body Structure:

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

Request Body Parameters:

Name	Type	Description
bold = required
query_spec	query_spec	The query that defines the resource model data to retrieve.
query_spec.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.provider.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 may be unset only if the cis.data.provider.resource_model.query_spec.limit is set to zero. Otherwise, vapi.std.errors.invalid_argument error will be thrown.
query_spec.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.
query_spec.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.provider.resource_model.query_spec.resource_models field (`FROM` clause).
query_spec.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.
query_spec.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.provider.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`. If the specified property is missing in the queried resource model or the property value is unset/null then the respective resource items should be excluded from the final result. This exclusion should happen for all comparison operators except the UNSET operator. The described behavior is the one applied in SQL where missing and null values are evaluated to unknown values and all predicates on these values do not match any resource.
query_spec.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. Applicable to numerical properties only, e.g. `long`, `double`. Cannot apply to `String` or `boolean`. GREATER_OR_EQUAL: Greater than or equal to operator. Applicable to numerical properties only, e.g. `long`, `double`. Cannot apply to `String` or `boolean`. LESS: Less than operator. Applicable to numerical properties only, e.g. `long`, `double`. Cannot apply to `String` or `boolean`. LESS_OR_EQUAL: Less than or equal to operator. Applicable to numerical properties only, e.g. `long`, `double`. Cannot apply to `String` or `boolean`. IN: Checks for equality with at least one of a list of values See cis.data.provider.resource_model.property_predicate.comparable_list for the set of the allowable comparable value types. NOT_IN: Checks for inequality with all values in a list. If the property is equal to any of the values in the list, evaluates to `false`. Otherwise, evaluates to `true` and the property is matched. See #comparableList for the set of the allowable comparable value types. LIKE: Pattern matching operator applicable to `String` properties. The `` character is used to define wildcard, i.e. a substitute for zero or more missing letters) before or after a given sequence of characters. If used at the end, it is interpreted as search for all properties whose value starts with the given characters. If used at the beginning, it is interpreted as search for all properties whose value ends with the given characters. For instance, if the input pattern is vm it will match property with value linux-vm, but not vm-linux. If the input pattern is vm* it will match property with value vm-linux, but not linux-vm. The wildcard character cannot be used in between other characters, i.e. in the middle of a pattern. It can be use more than once in a single pattern only in case it surrounds the pattern, i.e. both in the beginning and at the end of the pattern to perform substring (infix) search. For instance, if the input pattern is vm it will match property with value linux-vm-1, linux-vm, old-vm-linux, vm-linux and vm. The backslash character `\` is used for escaping. Hence, wildcard is escaped with the sequence \* and the escape character itself with the sequence \\. NOT_LIKE: Opposite of `LIKE`. The resource will be matched if the property does NOT match the provided pattern. UNSET: Checks whether the property has any value assigned to it or not, i.e. whether it is unset. Applicable only to optional properties or children of optional properties. A property is considered unset if its value is `null` or its parent property is unset. Empty array is not considered unset. For instance, the property `com.acme.PersonModel/phone/home` is considered unset if either it or its parent, i.e. `com.acme.PersonModel/phone` is equal to `null`. Should be used in conjunction with a `boolean` value for cis.data.provider.resource_model.property_predicate.comparable_value in order to determine whether to look for unset or set property. If `comparableValue` is set to `true`, matches resources with unset property, Otherwise, if `comparableValue` is set to `false`, matches resources whose property is set to some (any) value, except `null`.
query_spec.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 model key, i.e. property PROPERTY_MODEL_KEY, 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, LIKE, NOT_LIKE, UNSET]. 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, LESS_OR_EQUAL, LIKE, NOT_LIKE, or UNSET.
query_spec.filter.criteria[].comparable_list	opaque[]	The list of primitive values to test for equality with the property value when operator IN or NOT_IN is used. The list cannot be empty. See cis.data.provider.resource_model.property_predicate.comparable_value for the list of allowable primitive value types. Optional. It is only relevant when operator has value [IN, NOT_IN]. This field is optional and it is only relevant when the value of `operator` is one of IN or NOT_IN.
query_spec.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`.
query_spec.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.
query_spec.limit	long	The maximum number of result items to return. If used, the value should be a non-negative integer. A limit of zero means that no items shall be retrieved. Useful if the client is only interested in the total number of items matched by the query; in this case, cis.data.provider.resource_model.query_spec.return_total_count should be set to `true`, and the `offset` should be zero or unset. A non-zero limit can be used only if sorting criteria is applied, i.e. cis.data.provider.resource_model.query_spec.sort_criteria is set. Note that the service defines its own default limit that cannot be overridden here. If the specified value here is above that limit, an vapi.std.errors.invalid_argument error will be thrown for the particular query in order to indicate this violation. Optional. If unset, a default limit will be automatically assigned.
query_spec.offset	long	The offset into the result set. Could be used only if sorting criteria is applied, i.e. cis.data.provider.resource_model.query_spec.sort_criteria is set. If used, the value should be a non-negative integer. If the offset is `N` and the limit is non-zero, then items from `N` to `N + limit - 1` will be returned. If the limit is 0, then the offset should be zero or unset. Optional. If unset, it will be automatically assigned as 0.
query_spec.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.provider.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.provider.resource_model.query_spec.filter and the cis.data.provider.resource_model.query_spec.resource_models. It does not depend on the requested cis.data.provider.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.

Response:

HTTP Status Code: 200

Representation:

{
    "value" : {
        "total_count" : 1,
        "items" : [
            {
                "property_values" : [
                    "opaque_string_value",
                    "opaque_string_value"
                ]
            },
            {
                "property_values" : [
                    "opaque_string_value",
                    "opaque_string_value"
                ]
            }
        ],
        "properties" : [
            "string",
            "string"
        ]
    }
}

Response Type:

Name	Type	Description
bold = required
value	result_set	The resource model data retrieved for the provided query.
value.properties	string[]	The names of the (resource model) properties (as requested in cis.data.provider.resource_model.query_spec.properties) returned for each resource item in the result set. The position (index) of each model property in this list corresponds to the position of the model property value in each resource item's values list. That is, the name of each resource model property in the cis.data.provider.resource_model.resource_item.property_values list is given by the string with the same index (position) in this list. Could be empty only in case the cis.data.provider.resource_model.result_set.items list is empty.
value.items	resource_item[]	The list of result items. Each item corresponds to a particular resource that matched the conditions in the specified cis.data.provider.resource_model.query_spec instance and containing the property data retrieved for that resource. Could be empty if no items matched the query.
value.items[].property_values	opaque[]	The model property values for the resource. The name of each model property value is given by the model property name with the same index in cis.data.provider.resource_model.result_set.properties. In other words, the position of a property value in this list should be the same as the position of the property in the cis.data.provider.resource_model.result_set.properties list.
value.total_count	long	The total number of resources that matched the query, regardless of the actual number that is returned in cis.data.provider.resource_model.result_set.items. Optional. This value is set if and only if it has been explicitly requested in the query, i.e. if the cis.data.provider.resource_model.query_spec.return_total_count flag has been set to `true`.

Errors:

HTTP Status Code	Type	Description
400	invalid_argument	When provided with invalid query specification. See cis.data.provider.resource_model.query_spec for more details.
503	service_unavailable	If the service is too busy or if an external service required for the query execution is unavailable or times out, e.g. lost connection to DB.
401	unauthenticated	If a session has not been created, has expired due to inactivity or explicit log out.