Query requests
This chapter describes how to construct both object-based and operation-based query requests.
Request format
You use the HTTP POST method to send a metadata query API request to HCP. The POST request for both object-based and operation-based queries has these elements:
- A request URL.
- Optionally, if the URL starts with an IP address, an HTTP Host header.
- An Authorization header.
- An HTTP Content-Type header with one of these values:
- If the request body is XML, application/xml
- If the request body is JSON, application/json
- An HTTP Accept header to specify the response format: application/xml or application/json.
- Optionally, to send the query in gzip-compressed format:
- An HTTP Content-Encoding header with a value of gzip
- A chunked transfer encoding
NoteWhen using cURL to send the query in gzip-compressed format, the request must specify --data-binary. If the request specifies -d instead, HCP returns a 400 (Bad Request) error. - Optionally, to request that HCP return the response in gzip-compressed format, an HTTP Accept-Encoding header containing the value
gzip
or*
. The header can specify additional compression algorithms, but HCP uses only gzip. - Optionally, to request that HCP format the returned XML or JSON in an easily readable format, a prettyprint URL query parameter. The prettyprint parameter increases the time it takes to process a request. Therefore, you should use it only for testing purposes and not in production applications.
- A request body containing the query criteria and specifications for the contents of the result body. The entries you can specify depends on whether the request body is for an object-based query or an operation-based query.
- A request returns a 413 response code if the request exceeds the 8K Content-Length body limit.
Object-based query requests
The body of an object-based query request consists of entries in XML or JSON format.
XML request body for object-based queries
The XML request body for an operation-based query must contain a top-level queryRequest
entry and, except when requesting all available information, an operation
entry. All other entries are optional.
The XML request body has the format shown below. Entries at each hierarchical level can be specified in any order:
<queryRequest> <operation> <count>number-of-results</count> <lastResult> <urlName>object-url</urlName> <changeTimeMilliseconds>change-time-in-milliseconds.index </changeTimeMilliseconds> <version>version-id</version> </lastResult> <objectProperties>comma-separated-list-of-properties </objectProperties> <systemMetadata> <changeTime> <start>start-time-in-milliseconds</start> <end>end-time-in-milliseconds</end> </changeTime> <directories> <directory>directory-path</directory> ... </directories> <indexable>(true|false)</indexable> <namespaces> <namespace>namespace-name.tenant-name</namespace> ... </namespaces> <replicationCollision>(true|false)</replicationCollision> <transactions> <transaction>operation-type</transaction> ... </transactions> </systemMetadata> <verbose>(true|false)</verbose> </operation> </queryRequest>
The XML body for an operation-based query that requests all available operation records contains only this line:
<queryRequest/>
JSON request body for operation-based queries
The JSON request body for an operation-based query must contain an unnamed top-level entry and, except when requesting all available information, the operation
entry. All other entries are optional.
The JSON request body has the format shown below. Entries at each hierarchical level can be in any order:
{ "operation": { "count":"number-of-results", "lastResult":{ "urlName":"object-url", "changeTimeMilliseconds":"change-time-in-milliseconds.index", "version":version-id }, "objectProperties":"comma-separated-list-of-properties", "systemMetadata":{ "changeTime":{ "start":start-time-in-milliseconds, "end":end-time-in-milliseconds }, "directories":{ "directory":["directory-path",...] }, "indexable":"(true|false)", "namespaces":{ "namespace":["namespace-name.tenant-name",...] }, "replicationCollision":"(true|false)", "transactions":{ "transaction":["operation-type",...] } }, "verbose":"(true|false)" } }
For the namespace
, directory
, and transaction
entries, the square brackets shown in this format are required.
The JSON body for an operation-based query that requests all available operation records contains only this line:
{}
Request object body contents
The following sections describe the entries in an object-based metadata query API request body.
Top-level entry
XML has a single top-level queryRequest
entry. JSON has a corresponding unnamed top-level entry. All request bodies must contain this entry.
object entry
The object entry is required for object-based requests. It must contain the query
entry and can contain any combination of the other entries listed in the table below.
Entry | Valid values | Description |
query | A query expression | Specifies the query criteria. This entry is required. |
content Properties |
One of:
|
Returns information about the content properties available for use in queries. The default is To return only content properties, specify a |
count |
One of:
• |
Specifies the maximum number of results to return. If you omit this entry, HCP returns a maximum of one hundred results. HCP responds significantly faster to a request for all results when the request is for basic information only (that is, the value of the |
facets |
A comma-separated list of zero or more of:
|
Requests summary information for the returned values of the specified object properties. The values for this entry are case sensitive. |
object Properties | A comma-separated list of object properties |
Requests specific object properties to return for each All object entries include the If you specify this property, any |
offset | An integer between zero and 100,000 |
Skips the specified number of object entries in the complete result set. Specify this entry when you’re performing a paged query. The default is zero. |
sort | A comma-separated list of object properties and content properties with optional sort-order indicators | Specifies the sort order for object entries in the result set. |
verbose |
One of:
|
Specifies whether to return complete metadata for each object in the result set ( The default is If the request body contains both this property and the |
sort entry
You use the sort
entry to specify the order in which object-based query results are listed. The entry contains a comma-separated list of properties and a sort-order indicator, in this format:
object-property[+(asc|desc)][,.object-property[+(asc|desc)]]...
means sort in ascending order. asc
means sort in descending order. The default is desc
.asc
Objects are sorted by properties in the order in which the properties are listed in the sort
entry. For example, to sort query results in ascending order based on namespace name and descending order based on size within each namespace, specify this entry:
<sort>namespace+asc,size+desc</sort>
If you omit the sort
entry, the query results are listed in order of relevance to the query criteria.
You can sort only on single-valued content properties. You cannot sort on properties that can have multiple values.
facets entry
You use the facets
entry to request summary information for the returned values of specified object properties. For each specified property, HCP returns a list of up to one hundred object property values that occur most frequently in the result set. Each entry in the list has the number of objects that have each of the object property value. For example, if you specify retentionClass
in the facets entry, HCP returns a list of up to one hundred retention classes that occur with objects in the result set, along with the number of objects in each of those classes.
The value of the facets
entry is a comma-separated list of one or more of the object properties in the list below. Multiple properties can be specified in any order.
hold
Returns the numbers of objects in the result set that are on hold and not on hold.
namespace
Returns the names of namespaces that contain objects in the result set and the number of objects in the result set in each of those namespaces.
retention
For each of these retention values, returns the number of objects in the result set that have that value:
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
Returns the retention classes that are retention settings for objects in the result set and the number of objects in each retention class.
The count of objects in a retention class can include objects from more than one namespace. This is because multiple namespaces can have retention classes with the same name. To get an accurate count of the objects in a namespace that are in a specific retention class, restrict the query to a single namespace.
content-property-name
For Boolean and string content properties, returns the number of objects with the specified property value. For numeric and date properties, returns the number of objects in ranges of values.
You cannot use tokenized (full-text searchable) content properties with facets.
For numeric and date content properties, you specify the minimum and maximum values (range) for which to return information. You also specify the size of the sub-ranges (the interval) into which to divide the range.
You use the following format to specify the range and interval for facets for content properties with a type of integer, floating point, or date:
(start-value;end-value;+interval)
In this expression:
- start-value is inclusive, that is the range includes the specified value.
- Each entry in the response has an interval that is as close as possible to the specified interval, but not larger than it.
- end-value is inclusive.
- The last facet must have a full interval, even if end-value is less than the end of an interval.
For example, if the a facets
entry includes a salary
content property with a start-value of 10,000, an end-value of 99,999.99 and an interval of 10,000, the response will include ten entries for the property. The first entry will contain the number of employees with salaries of 10,000.00 through 19,999.99, the second will count salaries of 20,000.00 through 29,999.99, and the last will count salaries of 90,000 through 99,999.99.
However, if you specify an end-value of 100,000, the response will include 11 entries. The tenth entry will count salaries of 90,000.00 through 99,999.99, as before, but the response will include an additional entry that counts salaries of 100,000 through 109,999.99, even though you specified only 100,000
For dates:
- The start-value and end value must be either NOW, for the time when HCP processes the request, or a date-time value in this format:
yyyy-mm-ddThh:mm:ssZ
The time must be in UTC (coordinated universal time, also known as Greenwich Mean Time), not the local time, and you must specify the letter Z at the end of the format. For example, to specify noon Eastern Standard Time on February 10, 2013, specify 2013-02-10T17:00:00Z
- Follow these rules when you specify the interval:
- Specify the time using a number immediately followed by the calendar unit: SECOND, MINUTE, HOUR, DAY, MONTH, YEAR. You can use plurals of these values, for example 2MONTHS.
- Precede the time interval with a plus sign (+).
- You can combine intervals, such as +1YEAR+6MONTHS
This example requests facet information for three content properties: salary
, dateOfBirth
, and zip
:
<facets>salary(0;999999.99;50000), dateOfBirth(1900-01-01T00:00:00Z;*;+10YEARS),zip</facets>
The example consists of these facets:
- The
salary
facet requests the number of objects with salaries in the range zero through 999,999.00, broken out into intervals of 50,000. - The
dateOfBirth
facet requests the number of objects with birth dates in each ten-year interval from midnight, January 1, 1900 to now. - The
zip
facet requests the number of objects with each zip code that occurs in the result set. In this example, thezip
content property has a type of string, so you cannot specify a range or interval for it. This request returns facets only for zip codes that have at least one matching object.
Query expressions
With object-based queries, you specify a query expression in the query
request entry. Query expressions have this format:
[+|-]criterion [[+|-]criterion]...
In this expression, [+|-] is an optional Boolean operator and criterion is one of:
- A single text-based or property-based criterion.
- One or more criteria in parentheses, in this format:
([+|-]criterion [[+|-]criterion]...)
In this expression, criterion
can be a single criterion or one or more criteria in parentheses.
For example, here is one possible query expression:
-(namespace:"finance.europe") +(retention:0 index:1)
Query expressions can contain only valid UTF-8 characters.
Text-based criteria
Text-based criteria let you perform queries based on object paths and the full-text content of custom metadata. Queries that use text-based criteria find objects with matching custom metadata only in namespaces that are configured to support full-text searches of custom metadata.
To perform queries based on object paths only or on custom metadata content only, use property-based criteria.
A single text-based criterion is a text string consisting of one or more UTF-8 characters. This string is interpreted as one or more search terms, where each search term is a sequence of either alphabetic or numeric characters. All other characters, except wildcards, are treated as term separators.
For example, the string product123
contains two search terms — product
and 123
. A query based on this string finds objects with paths or custom metadata that contains at least one of product
and 123
.
Search terms match only complete alphabetic or numeric strings in paths or custom metadata. For example, the text strings AnnualReport
, 2012
, and AnnualReport_2012
match the object named AnnualReport_2012.pdf. A query expression with a text string such as Annual
or 201
does not match this object.
Similarly, to query for objects with a path or custom metadata that contains the word product
, you need to use the complete word product
as the text string. A query expression with a text string such as prod
does not match objects with a path or custom metadata containing product
.
Search terms are not case sensitive. Therefore, the text strings AnnualReport
, Annualreport
, and annualreport
are equivalent.
Common words such as a
and is
are valid search terms. For example, a query containing the text string A3534
matches all objects with paths and custom metadata that contain the word a
. To prevent such a match, use a phrase as described below.
To specify a negative number as a text-based criterion, enclose the criterion term in double quotation marks ("); for example, "-3121".
To specify a phrase as a criterion, put the text string in double quotation marks. A phrase matches paths and custom metadata that contain each of the alphabetic or numeric search terms within the quotation marks in the specified order, but any special characters or white space between the individual strings is ignored. For example, the phrase product 123
matches custom metadata that contains any of these strings:
product 123 product123 product_123
You can precede a text-based criterion with one of these Boolean operators:
Plus sign (+)
Objects in the result set must contain the search term following the plus sign.
Minus sign (-)
Objects in the result set must not contain the search term following the minus sign.
For example, this query expression finds objects where the path and custom metadata do not contain the string product
.
-product
If a value is in quotation marks, the Boolean operator comes before the opening quotation mark. For example, this query expression finds objects with paths or custom metadata that contains the phrase wetland permit
:
+"wetland permit"
A plus sign in front of a string that is not all-alphabetic or all-numeric finds paths and custom metadata that match at least one of the search terms. For example, the following expression matches paths and custom metadata that contain either the string product
or the number 456
:
+product456
A minus sign in front of a string that is not all-alphabetic or all-numeric finds paths that contain none of the search terms. For example, the following expression matches all paths and custom metadata that do not contain the string product
or the number 456
:
-product456
You can use these wildcard characters in or at the end of the text string for a text-based criterion:
Question mark (?)
Represents a single character
Asterisk (*)
Represents any number of consecutive printable characters, including none
These characters do not function as wildcards when included within double quotation marks (").
Wildcards are not valid at the beginning of a text string. For example, the query expression on the top is valid; the query expression on the bottom is not:
Valid: princ* Invalid: *cipal
You can use multiple wildcards in a criterion. Two asterisks next to each other are treated as a single asterisk. Asterisks with characters between them are treated as separate wildcards. For example, the criterion below matches the path /Conflicts.txt:
c**nflict*
Similarly, in an all
query, the criterion below matches any path with at least two directories preceding the object in the path:
/*/*/**
Two question marks next to each other are treated as separate wild cards. For example, the criterion below does not match the path /Conflicts.txt:
c??nflict*
Wildcards between text that the metadata query engine considers to be separate search terms are not valid. For example, the search string below does not match the path test1.txt because the wildcard is between an alphabetic character and a numeric character:
tes*1
Property-based criteria
Property-based criteria let you query for objects based on specified object property values. The format for a simple property-based criterion is:
property:value
For example, this expression finds objects that are on hold:
hold:true
When querying for a value that’s a negative number, enclose the value in double quotation marks ("). For example, this query expression finds objects with the retention setting -2:
retention:"-2"
The special property based criterion *:* matches all objects in all namespaces searchable by the user.
You can precede a criterion or an individual property value with one of these Boolean operators:
Plus sign (+)
Objects in the result set must contain the criterion or value following the plus sign.
Minus sign (-)
Objects in the result set must not contain the criterion or value following the minus sign.
For example, this query expression finds objects that are not on hold:
-hold:true
A property-based criterion can specify multiple values for a single property. To specify multiple values, use this format:
property:([+|-]value [[+|-]value]...)
In this format, the parentheses are required.
For example, this query expression finds objects in either the HlthReg-107 or HlthReg-224 retention class:
retentionClass:(HlthReg-107 HlthReg-224)
This query expression finds objects with custom metadata that contains the string finance
but not the string foreign
.
customMetadataContent:(+finance -foreign)
When you specify multiple values for a single property, you can combine values that are preceded by Boolean operators with values that do not have Boolean operators. In this case, objects that match the property values that are not preceded by Boolean operators may or may not appear in the result set, but objects that match the terms without Boolean operators are sorted higher in the query results than objects that don’t match those terms.
For example, this query expression finds objects that have custom metadata that contains both the terms quarterly report
and accounting department
or only the term quarterly report
:
customMetadataContent:(+"quarterly report" "accounting department")
Objects that contain both terms are sorted higher in the query results.
You can query based on ranges of values for properties with numeric, string, or date data types. These properties are accessTime
, accessTimeString
, changeTimeString
, dpl
, hash
, hashScheme
, ingestTime
, ingestTimeString
, retention
, retentionClass
, retentionString
, size
, updateTime
, updateTimeString
, and utf8Name
. You can also query based on ranges for content properties with numeric, string or date data types.
Criteria that query for a range of values can have either of these formats:
- For a range that includes the start and end values:
property:[start-valueTOend-value]
In this format, the square brackets are required.
For example, this query expression finds objects that were ingested from 0800 through 0900 UTC on March 1, 2012, inclusive:
ingestTimeString:[2012-03-01T08:00:00-0000 TO 2012-03-01T09:00:00-0000]
- For a range that does not include the start or end values:
property:{start-valueTOend-value}
In this format, the curly braces are required.
For example, this query expression finds objects that have names that occur alphabetically between Brown_Lee.xls and Green_Chris.xls, exclusive of those values:
utf8Name:{Brown_Lee.xls TO Green_Chris.xls}
You can mix square brackets and curly braces in an expression. For example, this query expression finds objects that were ingested from 0800 to 0900 UTC on March 1, 2012, including objects that were ingested at 0800 but excluding objects that were ingested at 0900:
ingestTimeString:[2012-03-01T08:00:00-0000 TO 2012-03-01T09:00:00-0000}
When querying for a range of property values, you can precede the whole criterion with a Boolean operator but you cannot precede an individual value with a Boolean operator. For example, the query expression on the first line is valid; the criterion on the second line is not:
Valid:+retentionString:[2013-07-01T00:00:00 TO 2013-07-31T00:00:00] Invalid: retentionString:[+2013-07-01T00:00:00 TO 2013-07-31T00:00:00]
When querying for a range of values, you can replace a value with an asterisk (*) to specify an unlimited range. For example, this query expression finds objects with a size equal to or greater than two thousand bytes:
size:[2000 TO *]
This query expression finds objects with change times before 9:00 AM, March 1, 2012 in the local time zone of the HCP system:
changeTimeString:[* TO 2012-03-01T09:00:00}
You can use the question mark (?) and asterisk (*) wildcard characters when specifying values for these object properties:
- customMetadataContent
- hash
- hashScheme
- retentionClass
- objectPath
- utf8Name
- content properties
For example, this query expression finds objects assigned to any retention class starting with HlthReg, such as HlthReg-107 or HlthReg-224:
retentionClass:HlthReg*
The question mark and asterisk characters do not function as wildcards when included within double quotation marks (").
Wildcards are not valid at the beginning of a property value. For example, the query expression on the first line is valid; the query expression on the second line is not:
Valid: utf8Name:princ* Invalid: utf8Name:*cipal
Query expression considerations
These considerations apply to query expressions, whether they contain property-based criteria, text-based criteria, or a combination of both:
- If the query expression consists of a single criterion without a Boolean operator, objects in the result set must meet the criterion. For example, this query expression finds objects with custom metadata that contains the string
accounting
:customMetadataContent:accounting
The expression above is equivalent to this expression that uses the plus sign (+):
+customMetadataContent:accounting
- If a query expression consists of multiple criteria without Boolean operators, objects in the result set must meet at least one of the criteria. For example, this query expression finds objects that have a retention setting of Deletion Allowed or are on hold or will be shredded on deletion:
retention:0 hold:true shred:true
- The greater the number of criteria an object meets, the higher the object is in the default sort order. For example, with this query expression, objects that match all three criteria are sorted higher than those that match only two, and those that match only two are sorted higher than those that match only one:
retention:0 hold:true shred:true
- If a plus sign precedes some search criteria but not others, the criteria that are not preceded by a plus sign have no effect on which objects are returned. For example, this query expression finds objects that have a utf8Name property with the value Q1_2012.ppt, regardless of whether they are in the finance namespace owned by the europe tenant:
+utf8Name:"Q1_2012.ppt" namespace:"finance.europe"
Objects that match the namespace criterion are sorted higher in the result set than those that do not match it.
- If a minus sign precedes some search criteria but not others and no criteria have plus signs, the query expression finds objects that do not match the criteria preceded by the minus signs and do match at least one of the criteria without a Boolean operator. For example, this query expression finds objects that are not in the finance namespace owned by the europe tenant and can be deleted.
-namespace:"finance.europe" retention:0
This query finds objects that are not in the finance namespace owned by the tenant named europe and either can be deleted or can be indexed (or both):
-namespace:"finance.europe" retention:0 index:1
- If a Boolean operator precedes an opening parenthesis, that operator applies to the entire set of criteria inside the parentheses, not the individual criteria. For example, this query expression finds objects that are on hold or have a retention setting of Deletion Prohibited:
+(hold:true retention:"-1")
- These characters have special meaning when specified in query expressions:
? * + - ( ) [ ] { } " :
To specify one of these characters in a query expression, precede the character with a backslash (\). To specify a backslash in a query expression, precede the backslash with another backslash.
customMetadataContent property
To search for objects based on the full-text content of custom metadata, you specify the customMetadataContent
property in a query expression. Criteria that use this property find objects only in namespaces that have full-text indexing of custom metadata enabled.
When custom metadata is indexed for full-text searching, the XML is treated as text, not as a structured document. Similarly, the customMetadataContent
property value is treated as text.
To use the customMetadataContent
property to query for any element name, attribute name, element value, or attribute value that matches a text string, use a query expression with this format:
customMetadataContent:text-string
If the text string consists of more than a single string of alphabetic or numeric characters, enclose the entire value in double quotation marks (").
To query for a combination of elements and attribute names and values, use a query expression with either of these formats:
customMetadataContent:"element-name. attribute-name.attribute-value...element-value.element-name" <![CDATA[customMetadataContent:"<element-name attribute-name=attribute-value...>element-value</element-name>"]]>
The two formats are equivalent. The first format is simpler. The second format uses well-formed XML.
When using the second format, enclose both the property and text string in the square brackets that mark the CDATA content, and enclose the text string in double quotation marks ("). The outer square brackets ([ ]) are also required, as are the outside angle brackets and exclamation mark.
To query for the value of a specific element, specify every attribute and attribute value for the element, not just the element name and value.
To query for the value of a specific attribute, regardless of which element it applies to, use this format:
customMetadataContent:"attribute-name.attribute-value"
You can use the asterisk (*) and question mark (?) wildcard characters when specifying customMetadataContent
property values that are not in quotation marks.
Here is some sample custom metadata that you might want to search:
<?xml version="1.0" ?> <weather> <location>Boston</location> <date>20121130</date> <duration unit="secs">180</duration> <temp> <temp_high unit="deg_F">31</temp_high> <temp_low unit="deg_F">31</temp_low> </temp> <velocity> <velocity_high unit="mph">17</velocity_high> <velocity_low unit="mph">14</velocity_low> </velocity> <conditions>partly cloudy</conditions> </weather>
Here are some examples of query expressions that use the customMetadataContent
property to search the XML:
- This query expression finds objects that have custom metadata with an element name, element value, attribute name, or attribute value that contains
Boston
:customMetadataContent:Boston
- This query expression finds objects that have custom metadata that contains the
location
element with a value ofBoston
:customMetadataContent:"location.Boston.location"
- This query expression finds objects that have custom metadata that contains the
velocity_high
element with a value of17
and theunit
attribute with a value ofmph
:customMetadataContent:"velocity_high.unit.mph.17.velocity_high"
- This query expression returns objects that have custom metadata that contains the
conditions
element with a value ofpartly cloudy
:customMetadataContent:"conditions.partly cloudy.conditions"
- This query expression finds objects that have custom metadata that contains the
date
element with a value of20121130
:<![CDATA[customMetadataContent:"<date>20121130</date>"]]>
- This query expression finds objects that have custom metadata that contains the
temp_high
element with a value of31
and theunit
attribute with a value ofdeg_F
:<![CDATA[customMetadataContent:"<temp_high unit=deg_F>31 </temp_high>"]]>"
aclGrant property
To query for objects based on the content of ACLs, you specify the aclGrant
property in a query expression. Valid values for this property have these formats:
"permissions" "permissions,USER[,location,username]" "permissions,GROUP,location,(ad-group-name|all_users|authenticated)"
In these formats:
permissions
One or more of these with no space between them:
R
Read_ACL
r
Read
W
Write_ACL
w
Write
d
Delete
If you specify only permissions as the
aclGrant
property value, the query expression finds objects with ACLs that grant you the specified permissions to any user or group.USER
Required when querying for objects with ACLs that grant permissions to a specified user.
If the credentials you specify in the query request are for a tenant-level user account that’s defined in HCP, you can find objects that have ACLs that grant the specified permissions to that user account by specifying only a value for
permissions
andUSER
.GROUP
Required when querying for objects with ACLs that grant permissions to a specific group of users.
location
The location in which the specified user or group is defined. Valid values are either:
- The name of an HCP tenant
- The name of an AD domain preceded by an at sign (@)
If the value for the
aclGrant
property includesall_users
orauthenticated
, location must be the name of an HCP tenant.username
The name of a user to which matching ACLs grant the specified permissions. Valid values are:
- The user name for a user account that’s defined in HCP.
- The user name for an AD user account. This can be either the user principal name or the Security Accounts Manager (SAM) account name for the AD user account.
ad-group-name
The name of an AD group to which the matching ACLs grant the specified permissions.
all_users
Represents all users.
authenticated
Represents all authenticated users.
The permissions in an aclGrant
property value must be specified in this order:
R, r, W, w, d
For example, to find objects that have ACLs that grant write and write_ACL permissions, and only those permissions, to the user rsilver who is defined in the europe tenant, specify this query expression:
aclGrant:"Ww,USER,europe,rsilver"
You can replace one or more permissions with the asterisk (*) wildcard character. When you do this, you still need to specify permissions in the correct order.
When you specify both an asterisk and one or more permissions, the metadata query API finds objects with ACLs that grant only the permissions you explicitly specify or that grant the permissions you explicitly specify and any permissions represented by the asterisk. For example, this query expression finds objects with ACLs that grant read, read_ACL, write, and write_ACL permissions and may also grant delete permission:
aclGrant:"RrWw*"
A single asterisk represents all the missing permissions in the location where it appears. Therefore, you don’t use consecutive asterisks. For example, in this query expression, the wildcard character represents any combination of write, write_ACL, and delete permissions:
aclGrant:"r*"
In this query expression, the wildcard character represents any combination of read and write_ACL permissions:
aclGrant:"R*w"
In this query expression, the wildcard character represents only read_ACL permission:
aclGrant:"*r"
You can specify multiple asterisks in a query expression. For example, this query expression finds objects with ACLs that grant read permission and any combination of other permissions to the AD group named managers that is defined in the corp.widgetco.com domain:
aclGrant:"*r*,GROUP,@corp.widgetco.com,managers"
By replacing all permission values with a single asterisk, you query for objects that have ACLs that grant any combination of permissions. For example, if you’re accessing the metadata query API with a tenant-level user account, this query expression finds objects with ACLs that grant any combination of permissions to that user account:
aclGrant:"*,USER"
aclGrant
without specifying a user and tenant returns every object in the index that has the ACL are searching. For instance, aclGrant:"r"
returns all objects that have the Read ACL set.These considerations apply when you specify the aclGrant
property in a query expression:
- The entire value for this property must be enclosed in double quotation marks (" ").
- The locations and usernames you specify are not case sensitive.
- The group names you specify, except for
all_users
andauthenticated
, are case sensitive. - The permission values you specify and the values USER and GROUP are case sensitive.
Query expression examples
Here are some examples of query expressions that use both text-based criteria and property-based criteria:
- This expression returns metadata for objects that have a retention setting of Deletion Allowed, are not on hold, and may or may not have a path or custom metadata that contains the term report:
+(retention:0) -(hold:true) report
- This expression returns metadata for objects in the finance namespace under the /Corporate/Employees directory that were ingested after March 1, 2012:
+(namespace:"finance.europe" objectPath:"/Corporate/Employees" ingestTimeString:[2012-03-01T00:00:00 TO *])
Paged queries with object-based requests
To use a paged query with object-based requests:
- In the first request, use a
count
entry with a value of zero to get a response that does not include any object records but contains a totalResults value that specifies the total number of objects that meet the query criteria. - In each request after the first, optionally specify a
count
entry. If you omit the count entry, the result set includes at most 100 objects. - After each request, check the value of the code property of the status entry to determine whether the result set contains the last object that meets the criteria:
- If the value is INCOMPLETE, more results remain. Request another page.
- If the value is COMPLETE, the result set includes the last object that meets the query criteria.
Paged queries with 100,000 or fewer matching objects
If no more than 100,000 objects match the query criteria, use the offset
entry to page through the result set. In each request after the first one with a count value greater than 0, include an offset
entry that specifies the number of results to skip when returning the next page of results. For example, if you specified a count
value of 50
for your first request, specify an offset
value of 50
for your second request.
Paged queries with more than 100,000 matching objects
If a large number of objects match the query criteria, a paged query can consume a large amount of memory. If more than 100,000 objects match the query criteria, limit memory use by using multiple paged queries. Each paged query should retrieve results for no more than 100,000 objects. To do this, use the changeTimeMilliseconds
as the basis for generating the paged queries, as follows:
Procedure
Issue a request with a count entry value of zero and a
changeTimeMilliseconds
criterion with a range from zero to some time in the past, such as this:<queryRequest> <object> <query>+changeTimeMilliseconds:[0 TO 1262304000000.00] +retentionClass:hlthReg-107</query> <count>0</count> </object> </queryRequest>
If the
count
property in the response is greater than 100,000, repeat this step with an earlierchangeTimeMilliseconds
end time until thecount
property in the response is no more than 100,000.Use a paged query with:
- A
changeTimeMilliseconds
criterion that specifies the same time as you used in the last request in step 1 - A
count
entry value that specifies the number of objects you want per page - An
offset
entry that you increment by thecount
value in each request
<queryRequest> <object> <query>+changeTimeMilliseconds:[0 TO 1150000000000.00] +retentionClass:hlthReg-107</query> <sort>changeTimeMilliseconds</sort> <count>50</count> <offset>150</offset> </object> </queryRequest>
Stop when the code property of the status entry in the response is COMPLETE.- A
Repeat step 1 above using a
Use a curly opening brace for the range so that the last entry in the previous result set is not included in the new results. For example, use achangeTimeMilliseconds
entry that specifies a range with start value equal to the end value of thechangeTimeMilliseconds
range you used in step 2.changeTimeMilliseconds
value like this:changeTimeMilliseconds:{1150000000000.00 TO 1341000000000.00]
Then repeat step 2 using the new query criteria.
Repeat step 3 until you retrieve the last matching object.
Use a value of * (for an unlimited range) as the end of thechangeTimeMilliseconds
range in the last paged query to ensure that you retrieve all objects including those that were most recently added.
Operation-based query requests
The body of an operation-based query request consists of entries in XML or JSON format.
XML request body for operation-based queries
The XML request body for an operation-based query must contain a top-level queryRequest
entry and, except when requesting all available information, an operation
entry. All other entries are optional.
The XML request body has the format shown below. Entries at each hierarchical level can be specified in any order:
<queryRequest> <operation> <count>number-of-results</count> <lastResult> <urlName>object-url</urlName> <changeTimeMilliseconds>change-time-in-milliseconds.index </changeTimeMilliseconds> <version>version-id</version> </lastResult> <objectProperties>comma-separated-list-of-properties </objectProperties> <systemMetadata> <changeTime> <start>start-time-in-milliseconds</start> <end>end-time-in-milliseconds</end> </changeTime> <directories> <directory>directory-path</directory> ... </directories> <indexable>(true|false)</indexable> <namespaces> <namespace>namespace-name.tenant-name</namespace> ... </namespaces> <replicationCollision>(true|false)</replicationCollision> <transactions> <transaction>operation-type</transaction> ... </transactions> </systemMetadata> <verbose>(true|false)</verbose> </operation> </queryRequest>
The XML body for an operation-based query that requests all available operation records contains only this line:
<queryRequest/>
JSON request body for operation-based queries
The JSON request body for an operation-based query must contain an unnamed top-level entry and, except when requesting all available information, the operation
entry. All other entries are optional.
The JSON request body has the format shown below. Entries at each hierarchical level can be in any order:
{ "operation": { "count":"number-of-results", "lastResult":{ "urlName":"object-url", "changeTimeMilliseconds":"change-time-in-milliseconds.index", "version":version-id }, "objectProperties":"comma-separated-list-of-properties", "systemMetadata":{ "changeTime":{ "start":start-time-in-milliseconds, "end":end-time-in-milliseconds }, "directories":{ "directory":["directory-path",...] }, "indexable":"(true|false)", "namespaces":{ "namespace":["namespace-name.tenant-name",...] }, "replicationCollision":"(true|false)", "transactions":{ "transaction":["operation-type",...] } }, "verbose":"(true|false)" } }
For the namespace
, directory
, and transaction
entries, the square brackets shown in this format are required.
The JSON body for an operation-based query that requests all available operation records contains only this line:
{}
Request operation body contents
The following sections describe the entries in an operation-based metadata query API request body.
Top-level entry
XML has a single top-level queryRequest
entry. JSON has a corresponding unnamed top-level entry. All request bodies must contain this entry.
operation entry
Except when requesting all available information, the operation
entry is required for operation-based queries. It can contain any combination of the entries listed in the table below.
Entry | Valid values | Description |
count |
One of:
|
Specifies the maximum number of operation records to return per request. If you omit this entry, HCP returns up to ten thousand operation records per request. |
lastResult | N/A | Specifies the last record returned by the previous query. Use this entry in paged queries to request additional results after an incomplete response. Omit this entry if you are not using a paged query or if this is the first request in a paged query. |
objectProperties | A comma separated list of object properties. |
Requests specific object property values for each object entry in the query results. If the request body contains both the |
systemMetadata | N/A | Specifies the properties to use as the query criteria. |
verbose |
One of:
|
Specifies whether to return complete metadata for each operation record in the result set ( The default is If the query request body contains both the |
lastResult entry
Use the lastResult
entry only in the second through final requests of a paged query. This entry identifies the last record that was returned in the previous query so that HCP can retrieve the next set of records. The entry contains the child entries described in the table below.
Entry | Valid values | Description |
urlName |
A fully qualified object URL, for example: http://finance.europe.hcp.example.com/rest/Presentations/Q1_2012.ppt
| Specifies the urlName value in the last operation record returned in response to the previous query. |
changeTime Milliseconds | A timestamp in milliseconds since January 1, 1970, at 00:00:00 UTC, followed by a period and a two-digit suffix | Specifies the changeTimeMilliseconds value in the last operation record returned in response to the previous query. |
version | A version ID | Specifies the version value in the last operation record returned in response to the previous query. |
systemMetadata entry
The systemMetadata
entry specifies the criteria that the returned operation records must match. The entry contains the child entries listed in the table below. Some of the subentries, such as changeTime
, have children. In this table, the parent entries are immediately followed by their children.
Entry | Valid values | Description |
changeTime | N/A |
Specifies the range of change times of the objects for which to return operation records. This entry can contain neither, one, or both of the If you omit this entry, HCP returns operation records for objects with change times between January 1, 1970, at 00:00:00 UTC and one minute before the time HCP received the request. |
start(child) |
One of:
|
Requests operation records for objects with change times on or after the specified date and time. This entry is a child entry of the The default is zero (January 1, 1970, 00:00:00 UTC). In the ISO 8601 format, you cannot specify a millisecond value. The time corresponds to zero milliseconds into the specified second. |
end(child) |
One of:
• • |
Requests operation records for objects with change times before the specified date and time. This entry is a child entry of the The default value is one minute before the time HCP received the request. In the ISO 8601 format, you cannot specify a millisecond value. The time corresponds to zero milliseconds into the specified second. If you specify a value that is less than one minute before the current time, ensure that all writes finished at least one minute ago so that you get results for the most recent operations. |
directories | N/A |
Specifies the directories to query. This entry contains zero or more If you omit this entry, HCP returns operation records for objects in all directories in the specified namespaces. |
directory(child) |
The path to the directory containing the objects for which to retrieve operation records. Start the path with a forward slash (/) followed by the name of a directory immediately below
|
Specifies a directory to query. This entry is a child of the If you query multiple namespaces, HCP returns operation records for the directory contents in each namespace in which the directory occurs. |
indexable |
One of:
|
Specifies whether to filter the returned operation records based on the object index setting. HCP returns deletion and purge records only for objects that had the specified setting at the time they were deleted or purged. If you omit this entry, HCP returns operation records for objects regardless of their index settings. |
namespaces | N/A |
Specifies the namespaces to query. This entry contains zero or more If the URL in the request starts with If you omit this entry and the URL starts with If you omit this entry and the URL starts with a tenant name, HCP returns operation records for the tenant's namespaces that the user has permission to search. |
namespace (child) |
A namespace name along with the name of the owning tenant, in this format: namespace-name.tenant-name | Specifies a namespace to query. This entry is a child of the namespaces entry. |
replication Collsion |
One of:
|
Specifies whether to filter the returned operation records based on whether the object is flagged as a replication collision. HCP returns deletion and purge records only for objects that were flagged as replication collisions at the time they were deleted or purged. If you omit this entry, HCP returns operation records for objects regardless of whether they are flagged as replication collisions. |
transactions | N/A |
Specifies the operation types for which to query. This entry contains up to five If you omit this entry, HCP returns records only for create, delete, and purge operations. |
transaction(child) |
One of:
|
Specifies a type of operation for which to return records. This entry is a child entry of the HCP returns prune and disposition records only when you explicitly request them. Objects in the default namespace don’t have prune or purge operation types. |
Paged queries with operation-based requests
To use a paged query with operation-based query requests:
- Optionally, specify a
count
entry in each request body. If you omit this entry, HCP returns ten thousand operation records per request. - For each request after the first, specify a
lastResult
entry containing the values of theurlName
,changeTimeMilliseconds
, andversion
properties in the last record returned in response to the previous request. - After each request, check the value of the code property of the
status
entry to determine whether the result set contains the last object that meets the criteria:- If the value is INCOMPLETE, more results remain. Request another page.
- If the value is COMPLETE, the result set includes the last object that meets the query criteria.
Object properties
The table below describes the object properties that you can specify in these contexts:
objectProperties
entrysort
entry- Query entry
In the sort
and objectProperties
entries, you specify only the object property name. In query expressions, you specify both the property name and one or more values for the property.
The properties listed below are also returned in response bodies. The verbose
and objectProperties
request entries determine which properties are returned.
Object property | Data type | Description | Query expression example |
accessTime | Long | The value of the POSIX atime attribute for the object, in seconds since January 1, 1970 at 00:00:00 UTC. |
accessTime: [1312156800 TO 1312243200] |
accessTime String1 | Datetime |
The value of the POSIX YYYY-MM-DDThh:mm:ssZ Z represents the offset from UTC, in this format: (+|-)hhmm The UTC offset is optional. If you omit it, the time is in the zone of the HCP system. For example, 2011-11-16T14:27:20-0500 represents the 20th second into 2:27 PM, November 16, 2011, EST. |
accessTimeString: [2012-03-01 T00:00:00 TO 2012-03-01 T23:59:59] |
acl2 | Boolean |
An indication of whether the object has an ACL. Valid values are:
This value is always |
acl:true |
aclGrant | String |
ACL content. This property can be used only in queries. It cannot be used in |
aclGrant:"Ww,USER, europe,rsilver" |
changeTime Milliseconds | String |
The time at which the object last changed. For delete, dispose, prune, and purge records, this is the time when the operation was performed on the object. The value is the time in milliseconds since January 1, 1970, at 00:00:00 UTC, followed by a period and a two-digit suffix. The suffix ensures that the change time values for versions of an object are unique. This property is not returned for objects with the NOT_FOUND operation type. For more information about this operation type, see the description of the operation entry. This property corresponds to the POSIX |
changeTimeMilliseconds: [1311206400000.00 TO 1311292800000.00] |
changeTime String1 | Datetime |
The object change time in ISO 8601 format: YYYY-MM-DDThh:mm:ssZ For more information about this format, see the description of the This property corresponds to the POSIX |
changeTimeString: [2012-03-21 T00:00:00 TO 2012-03-21 T23:59:59] |
custom Metadata2 | Boolean |
An indication of whether the object has custom metadata. Valid values are:
|
customMetadata:true |
custom Metadata Annotation | String | One or more comma-delimited annotation names. Annotation names are case-sensitive. |
customMetadata Annotation:inventory |
custom Metadata Content | String |
Custom metadata content. This property can be used only in queries. It cannot be used in |
customMetadata Content:city.Bath. city |
dpl | Integer | The DPL for the namespace that contains the object. |
dpl:2 |
gid3 | Integer | The POSIX group ID. | N/A |
hash4 | String |
The cryptographic hash algorithm used to compute the hash value of the object, followed by a space and the hash value of the object. In query expressions, the values you specify for both the hash algorithm and the hash value are case sensitive. You need to use uppercase letters when specifying these values. When using wildcard characters with this object property, instead of a space, separate the hash algorithm and the hash value with a wildcard character. In this case, do not enclose the value for this property in quotation marks. If you do not specify wildcard characters in the value for this property, you need to enclose the entire value for this property in double quotation marks. |
hash:"SHA-256 9B6D4..." |
hashScheme4 | String |
The cryptographic hash algorithm the namespace uses. In query expressions, the values you specify for this property are case sensitive. Do not enclose these values in quotation marks. |
hashScheme:SHA-256 |
hold2 | Boolean |
An indication of whether the object is currently on hold. Valid values are:
|
hold:false |
index2 | Boolean |
An indication of which parts of the object are indexed. Valid values are:
|
index:true |
ingestTime | Long | The time at which HCP stored the object, in seconds since January 1, 1970, at 00:00:00 UTC. |
ingestTime:[130947840 TO 1312156800] |
ingestTime String1 | Datetime |
The time at which HCP stored the object, in ISO 8601 format: YYYY-MM-DDThh:mm:ssZ For more information about this format, see the description of the |
ingestTimeString: [2012-03-01 T00:00:00 TO 2012-03-01 T23:59:59] |
namespace2 | String |
The name of the namespace that contains the object, in this format: namespace-name.tenant-name In query expressions, the values you specify for this property are not case sensitive. |
namespace: finance.europe |
objectPath4 | String |
The path to the object following rest, data, or fcfs_data, beginning with a forward slash (/). In query expressions, the values you specify for this property are not case sensitive and do not need to begin with a forward slash (/). |
objectPath:"/Corporate/Employees/45_Jane_Doe.xls" |
operation3 | String |
The type of operation the result represents. Possible values in a response body are:
PRUNED and PURGED do not apply to objects in the default namespace. Results for object-based queries have either the CREATED or NOT_FOUND operation type. NOT_FOUND means that the object has been deleted from the repository but has not yet been removed from the index. The NOT_FOUND operation type is returned only for queries that specify | N/A |
owner2 | String |
For objects in HCP namespaces, the user that owns the object. Valid values are:
In these values:
|
owner:"USER,europe,pdgrey" |
owner2 (continued) | String |
These considerations apply when you specify the
| |
permissions3 | Integer | The octal value of the POSIX permissions for the object. | N/A |
replicated3 | Boolean |
An indication of whether the object has been replicated. Possible values in a response body are:
| N/A |
replication Collision | Boolean |
An indication of whether the object is flagged as a replication collision. Valid values are:
|
replicationCollision:true |
retention | Long |
The end of the retention period for the object, in seconds since January 1, 1970, at 00:00:00 UTC. This value can also be:
|
retention:"-1" |
retentionClass4 | String |
The name of the retention class assigned to the object. If the object is not assigned to a retention class, this value is an empty string in the query results. In query expressions, the values you specify for this property are case sensitive. |
retentionClass:Reg-107 |
retention String1 | String |
The end of the retention period for this object in ISO 8601 format: YYYY-MM-DDThh:mm:ssZ For more information about this format, see the description of the This value can also be one of these special values:
In query expressions, these special values are case sensitive. In query results, this property also displays the retention class and retention offset, if applicable. |
retentionString: “2015-03-02T 12:00:00-0500” |
shred2 | Boolean |
An indication of whether the object will be shredded after it is deleted. Valid values are:
|
shred:true |
size | Long | The size of the object content, in bytes. |
size:[2000 TO 3000] |
type3 | String | The object type. In a response body, this value is always object . | N/A |
uid3 | Integer | The POSIX user ID. | N/A |
urlName3 | String |
The fully qualified object URL. For example: https://finance.europe.hcp.example.com/rest/Presentations/ Q1_2012.ppt | N/A |
updateTime | Long | The value of the POSIX mtime attribute for the object, in seconds since January 1, 1970, at 00:00:00 UTC. |
updateTime:[1309478400 TO 1312156800] |
updateTime String1 | Datetime |
The value of the POSIX YYYY-MM-DDThh:mm:ssZ For more information about this format, see the description of the |
updateTimeString: [2012-04-01 T00:00:00 TO 2012-04-30 T23:59:59] |
utf8Name4 | String |
The UTF-8-encoded name of the object. In query expressions, the values you specify for this property are case sensitive. |
utf8Name:23_John_Doe.xls |
version |
Unsigned long |
The version ID of the object. All objects, including those in the default namespace, have version IDs. This property is not returned for objects with the NOT_FOUND operation type. For more information about this operation type, see the operation entry, above. When you specify the version ID of an old version in a query expression, HCP returns information about the current version of the object. |
version:83920048912257 |
content-property-name4 | Depends on property type | The value of a content property. |
doctor_name: "John Smith" |
Notes:
|