Skip to main content
Hitachi Vantara Knowledge

Query responses

This chapter describes the response format for both object-based queries and operation-based queries.

NoteIn some situations, when you specify one or more namespaces in a query request, the result may differ depending on whether the query is object-based or operation-based.

XML response bodies

The format of an XML query response differs depending on the type of the query.

XML reponse body for object-based queries

An XML response for an object-based query has this format:

<?xml version='1.0' encoding='UTF-8'?>
<queryResult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="/static/xsd/query-result-6.0.xsd">
    <query>
        <expression>query-request-entry</expression>
    </query>
    <resultSet>
         <object
             changeTimeMilliseconds="change-time-in-milliseconds.index"
             version="version-id"
             urlName="object-url"
             operation="operation-type"
             Additional properties if specified in the objectProperties request entry
                or if the verbose request entry specifies true
         />
        Additional object entries
    </resultSet>
    <status
         totalResults="total-object-count"
         results="returned-object-count"
        message=""
         code="COMPLETE|INCOMPLETE" />
    The contentProperties entry below is included only if the request included a
    contentProperties entry with a vlaue of true.
    <contentProperties>
         <contentProperty>
             <expression>content-property-expression</expression>
             <name>content-property-name</name>
             <type>data-type</type>
             <multivalued>true|false</multivalued>
             <format>data-format</format>
         </contentProperty>
         Additional content properties
    </contentProperties>
    The facets entry below is included only if the request included a facets entry.
    <facets>
        One or more of the following facet entries depending on the properties specified
         in the facets request entry
         <facet
         property="hold">
         <frequency
             count="object-count"
             value="true" />
         <frequency
             count="object-count"
             value="false" />
         </facet>
         <facet
             property="namespace">
             <frequency
                 count="object-count"
                 value="namespace-name.tenant-name" />
            Up to 99 additional frequency entries
             </facet>
             <facet
                 property="retentionClass">
                 <frequency
                 count="object-count"
                 value="retention-class-name" />
            Up to 99 additional frequency entries
         </facet>
         <facet
             property="retention">
             <frequency
                 count="object-count"
                 value="initialUnspecified" />
             <frequency
                 count="object-count"
                 value="neverDeletable" />
             <frequency
                 count="object-count"
                 value="expired" />
             <frequency
                 count="object-count"
                 value="not expired" />
             </facet>
            Zero or more of the following facet entries depending on the number of content
             properties in the facets request entry:
             <facet
                 property="content-property-name">
                 <frequency
                     count="object-count"
                     value="value-or-facet-range" />
                Up to 99 additional range frequency entries
         </facet>
    </facets>
</queryResult>

XML response body for operation-based queries

An XML response for an operation-based query has this format:

<?xml version='1.0' encoding='UTF-8'?>
<queryResult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="/static/xsd/query-result-6.0.xsd">
    <query
         start="start-time-in-milliseconds"
         end="end-time-in-milliseconds" />
    <resultSet>
         <object
             changeTimeMilliseconds="change-time-in-milliseconds.index"
             version="version-id"
             urlName="object-url"
             operation="operation-type"
             Additional properties if specified in the objectProperties request entry
                 or if the verbose request entry specifies true
         />
        Additional object entries
    </resultSet>
    <status
         results="returned-record-count"
         message=""
         code="COMPLETE|INCOMPLETE" />
    </queryResult>

JSON response bodies

The format of a JSON query response differs depending on the type of the query.

JSON response body for object-based queries

A JSON response for an object-based query has this format:

{
    "queryResult":{
        "query":{
             "expression":"query-request-entry"
         },
         "resultSet":[{
             {
                  "urlName":"object-url",
                 "operation":"operation-type",
                 "changeTimeMilliseconds":"change-time-in-milliseconds.index",
                 "version":version-id,
                Additional properties if specified in the objectProperties request entry or
                  if the verbose request entry specifies true
             },
            Additional object entries
        }],
             "status":{
             "totalResults":total-object-count,
             "results":returned-object-count,
             "message":"",
             "code":"COMPLETE|INCOMPLETE"
         },
         The contentProperties entry below is included only if the request included a
        contentProperties entry with a value of true
         "contentProperties":[{
             "contentProperty":{
             “expression":content-property-expression,
             "name":content-property-name,
             "type":data-type,
             "multivalued":true|false,
             "format":data-format,
         }
         Additional content properties
     }],
    The facets entry below is included only if the request included a facets entry.
     "facets":{
         One or more of the following facet entries depending on the properties
         specified in the facets request entry:
            "facet":[{
             "property":"hold",
             "frequency":[{
                 "value":"true",
                 "count:object-count
                 }, {
                "value":"false",
                "count":object-count
                 }]
                 }, {
                    "property":"namespace",
                    "frequency":[{
                        "value":"namespace-name.tenant-name",
                        "count":object-count
                    Up to 99 additional value properties
                    }]
                }, {
                    "property":"retentionClass",
                     "frequency":[{
                         "value":"retention-class-name",
                         "count":object-count
                         Up to 99 additional value properties
                          }]
                      }, {
                           "property":"retention",
                           "frequency":[{
                              "value":"initialUnspecified",
                              "count":object-count
                         },{
                             "value":"neverDeletable",
                              "count":object-count
                          },{
                              "value":"expired",
                              "count":object-count
                          },{
                             "value":"not expired",
                              "count":object-count
                         ]
                              Zero or more of the following facet entries depending
                              on whether the number of defined content properties in the
                              facets request entry.
                      },{
                         property:"content--property-name",
                          frequency:[{
                              count:"object-count",
                              value:"value-or-facet-range"
                          },{
                             Up to 99 additional range frequency entries
                   }
                 }]
          }]
    }
}

JSON response body for operation-based queries

A JSON response for an operation-based query has this format:

{
    "queryResult":{
     "query":{
        "end":end-time-in-milliseconds,
         "start":start-time-in-milliseconds
     },
    "resultSet":[{
        {
            "urlName":"object-url",
            "operation":"operation-type",
            "changeTimeMilliseconds":"change-time-in-milliseconds.index",
            "version":version-id,
            Additional properties if specified in the objectProperties request entry or
            if the verbose request entry specifies true
             },
            Additional object entries
        }],
        "status":{
             "results":returned-record-count,
             "message":"",
             "code":"COMPLETE|INCOMPLETE"
         }
    }
}

Response body contents

Both XML and JSON have a single top-level queryResult entry. The queryResult entry contains one of each of the entries listed in the list below.

  • query

    For object-based queries, a container for the query expression.

    For operation-based queries, a specification of the time period that the query covers. The results include only operation records for objects with change times during this period.

  • resultSet

    A container for the set of object entries representing the objects or operation records that match the query.

  • status

    Information about the response, including the number of returned records and whether the response completes the query results.

  • contentProperties

    (object-based queries only)

    For queries that contained a contentProperties entry with a value of true, a list of the available content properties.

  • facets

    (object-based queries only)

    Summary information about property values that appear in the result set.

    This entry is returned only if the query request included the facets entry.

query entry

The query entry contains the entry and properties described in the list below.

  • expression

    (entry, object-based queries only)

    A container for value of the query request entry.

  • start

    (property, operation-based queries only)

    The value of the start request property, in milliseconds since January 1, 1970, at 00:00:00 UTC.

    If you omitted the start entry in the request, this value is 0 (zero).

  • end

    (property, operation-based queries only)

    The value of the end request property, in milliseconds since January 1, 1970, at 00:00:00 UTC.

    If you omitted the end entry in the request, this value is one minute before the time HCP received the request.

resultSet entry

The resultSet entry has one child object entry for each object or operation record that matches the query criteria.

NoteThe metadata query API does not return results for open objects (that is, objects that are still being written or were never closed).

object entry

In XML, the object entries are child elements of the resultSet entry. In JSON, the object entries are unnamed objects in the resultSet entry.

The information that the object entry provides depends on the type of the query request:

  • For object-based queries, each object entry provides information about an individual object.
  • For operation-based queries, each object entry provides information about an individual create, delete, dispose, prune, or purge operation and the object affected by the operation.

The object entry always contains these object properties:

  • changeTimeMilliseconds
  • operation
  • urlName
  • version

The object entry can contain other object properties depending on the value of the verbose request entry or the value of the objectProperties request entry.

status entry

The status entry has the properties listed below.

  • code

    An indication of whether all results have been returned:

    • COMPLETE

      All results have been returned. This value is returned if the response includes all results or if the response includes the last result for a paged query.

    • INCOMPLETE

      Not all results have been returned. This value is returned if any of these apply:

      • The count request entry is smaller than the number of objects or operation records that meet the query criteria.
      • For object-based queries, the count request entry is not specified and more than one hundred objects meet the query criteria.
      • For operation-based queries, the count request entry is not specified and more than ten thousand operation records meet the query criteria.
      • The response is incomplete due to an error encountered in executing the query.

    You can retrieve additional results by resubmitting the request with an offset entry (for object-based queries) or a lastResult entry (for operation-based queries).

  • message

    Always an empty string.

  • results

    The number of results returned.

  • totalResults

    For object-based queries, the total number of indexed objects that meet the query criteria.

    This property is not returned for operation-based queries.

contentProperties entry

If the request included a contentProperties entry with a value of true, the result has a contentProperties entry containing zero or more contentProperty entries. Each contentProperty entry contains the entries listed below.

  • expression

    The expression that specifies how HCP locates the property value in the custom metadata XML.

  • format

    The pattern used to parse a number or date value in the XML custom metadata. For example, the format used for dollar values for a content property with a type of float might be $#,##0.00.

    This entry is included for integer, float, and date types only.

  • multivalued

    An indication of whether the property can have multiple values.

  • name

    The content property name.

  • type

    The content property data type. One of:

    • BOOLEAN
    • DATE
    • FLOAT
    • INTEGER
    • TOKENIZED (full-text searchable string)
    • STRING

facets entry

The facets response entry has one or more child facet entries, as described below.

  • facet

    Child of the facets entry. This entry contains the property property and one or more frequency entries.

  • property

    (property)

    Property of the facet entry. The value for this property is one of:

    • hold
    • namespace
    • retention
    • retentionClass
    • content-property-name
  • frequency

    (child)

    Child of the facet entry. This entry contains the count and value properties.

    This entry is returned only for property values that appear in the result set.

    frequency entries are listed in descending order based on the value of the count property. A query response can contain a maximum of one hundred frequency entries.

  • count

    (property)

    The number of objects in the result set with the property value identified by the value property.

  • value

    (property)

    An object property value that applies to one or more objects in the result set.

    The value of this property depends on the property value of the parent facet entry. When the value of the parent facet entry property property is:

    • hold, this value is either true or false.
    • retention, this value is one of:
      • initialUnspecified

        For objects with a retention setting of Initial Unspecified

      • neverDeletable

        For objects with a retention setting of Deletion Prohibited

      • expired

        For objects with a retention setting that is Deletion Allowed or a specific date in the past

      • not expired

        For objects with a retention setting that is a specific date in the future

    • retentionClass, this value is the name of a retention class for an object in the result set.
    • namespace, this value identifies a namespace that contains an object in the result set. The value has this format:
      namespace-name.tenant-name
    • content-property-name, this value is a value of the named content property that occurs in the result set.

HTTP status codes

The table below describes the possible HTTP status codes for metadata query API requests.

CodeMeaningDescription
200OKHCP successfully processed the query.
400Bad Request

The request syntax is invalid. Possible reasons for this error include:

  • The query request contains an invalid URL query parameter.
  • The query request body contains invalid XML or JSON (for example, an invalid entry name).
  • The query request body contains an invalid entry value, such as a malformed version ID or invalid directory path.
  • One of the sort, facet, query, or objectProperties request entries contains an invalid object property.
  • The request contains a Content-Encoding header that specifies gzip, but the request body is not in gzip-compressed format.
  • The cURL -d option is specified instead of the --data-binary option with a request body in gzip-compressed format
  • For object-based queries, the query request entry specifies a query expression that is not in UTF-8 format.
  • For operation-based queries, the query request specifies a namespace that does not exist.
  • For object-based queries, HCP has insufficient memory to process and return query results. To avoid this error, take one or more of these actions:
    • Specify more precise query criteria to return fewer results.
    • Omit the sort request entry.
    • Omit the facets request entry.

If more information about the error is available, the response includes the HCP-specific X‑HCP-ErrorMessage HTTP header.

403Forbidden

One of:

  • The request does not include an Authorization header or hcp-ns-auth cookie.
  • The Authorization header or hcp-ns-auth cookie specifies invalid credentials.
  • The Authorization header or hcp-ns-auth cookie specifies credentials for a system-level user account that is not configured to allow use of the metadata query API.
  • The Authorization header or hcp-ns-auth cookie specifies credentials for a system-level user account, but the URL specifies an HCP tenant that has not granted administrative access to system-level users.
  • For operation-based queries, the Authorization header or hcp-ns-auth cookie specifies credentials for a tenant-level user, but the query specifies a namespace for which that user account does not have search permission.
  • For operation-based queries, the Authorization header or hcp-ns-auth cookie specifies credentials for a system-level user account that is configured to allow use of the metadata query API and the URL specifies admin, but the request body specifies a namespace in a tenant that has not granted administrative access to system-level users.
  • The tenant specified in the URL does not exist.

If more information about the error is available, the response includes the HCP-specific X‑HCP-ErrorMessage HTTP header.

406Not Acceptable

One of:

  • The request does not have an Accept header, or the Accept header does not specify application/xml or application/json.
  • The request has an Accept-Encoding header that does not specify gzip or *.
413Request Entity Too LargeRequest body exceeds the 8k limit.
415Unsupported Media Type

One of:

  • The request does not have a Content-Type header, or the Content-Type header does not specify application/xml or application/json.
  • The request has a Content-Encoding header with a value other than gzip.
500Internal Server Error

An internal error occurred. Try the request again, gradually increasing the delay between each successive attempt.

If this error happens repeatedly, contact your tenant administrator.

503Service UnavailableHCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt.

HTTP response headers

The response to a valid query request includes a Transfer-Encoding header with a value of chunked and an Expires header with a value of Thu, 01 Jan 1970 00:00:00 GMT.

If the query request specifies a gzip-compressed response, the response includes a Content-Encoding header with a value of gzip.

If HCP can provide additional information about an invalid query request, the response has an X-HCP-ErrorMessage header describing the error.

 

  • Was this article helpful?