Query responses
This chapter describes the response format for both object-based queries and operation-based queries.
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 oftrue
, 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.
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.
- The
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 theproperty
property and one or morefrequency
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 thecount
andvalue
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 thecount
property. A query response can contain a maximum of one hundredfrequency
entries.count
(property)
The number of objects in the result set with the
property
value identified by thevalue
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 parentfacet
entry. When the value of the parentfacet
entryproperty
property is:hold
, this value is eithertrue
orfalse
.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.
Code | Meaning | Description |
200 | OK | HCP successfully processed the query. |
400 | Bad Request |
The request syntax is invalid. Possible reasons for this error include:
If more information about the error is available, the response includes the HCP-specific |
403 | Forbidden |
One of:
If more information about the error is available, the response includes the HCP-specific |
406 | Not Acceptable |
One of:
|
413 | Request Entity Too Large | Request body exceeds the 8k limit. |
415 | Unsupported Media Type |
One of:
|
500 | Internal 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. |
503 | Service Unavailable | HCP 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.