Skip to main content

We've Moved!

Product Documentation has moved to docs.hitachivantara.com
Hitachi Vantara Knowledge

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.

EntryValid valuesDescription
queryA query expressionSpecifies the query criteria. This entry is required.

content

Properties

One of:

  • true

    Return information for all content properties.

  • false

    Do not return any information on content properties.

Returns information about the content properties available for use in queries.

The default is false.

To return only content properties, specify a count entry with a value of 0.

count

One of:

  • -1, to request all results
  • 0, to request a response that includes only the object count and, if requested, content properties and facets.
  • An integer between one and 10,000

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 verbose entry is (or defaults to) false and the objectProperties entry is omitted). Additionally, a request for all results that includes the verbose entry with a value of true or that includes the objectProperties entry may not return all the expected results due to a connection timeout.

facets

A comma-separated list of zero or more of:

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

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 object entry in the query results.

All object entries include the operation, version, urlName, and changeTimeMilliseconds properties, so you don’t need to specify them in this property.

If you specify this property, any verbose property is ignored.

offsetAn 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.

sortA comma-separated list of object properties and content properties with optional sort-order indicatorsSpecifies the sort order for object entries in the result set.
verbose

One of:

  • true

    Return all object properties.

  • false

    Return only the object URL, version ID, operation, and change time.

Specifies whether to return complete metadata for each object in the result set (true) or only the object URL, version ID, operation type, and change time.

The default is false.

If the request body contains both this property and the objectProperties property, this property is ignored.

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)]]...

asc means sort in ascending order. desc means sort in descending order. The default is asc.

Sort order

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.

Sorting on content properties

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.

Facet object properties

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.

Content property facet ranges

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, the zip 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.

TipYou can use the Metadata Query Engine Console to generate query expressions. To do this, construct a query on the Structured Query page and then click the Show as advanced query link. The resulting advanced query can be used as a query expression in an object-based query request.

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
Boolean operators in text-based criteria

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
Wildcard characters in text-based criteria

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.

Boolean operators with property-based criteria

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
Multiple values for a single property

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.

Value ranges

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}
Noteutf8Name property values are case sensitive and are ordered according to the positions of characters in the UTF-8 character table.

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}
Wildcard characters in property-based searches

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.

TipIf you frequently search for values of a particular element or attribute, use a content property that corresponds to that element or attribute, as content property searches are more efficient than customMetadataContent searches. If the required content property does not exist, ask your tenant administrator to create one.

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 of Boston:
    customMetadataContent:"location.Boston.location"
  • This query expression finds objects that have custom metadata that contains the velocity_high element with a value of 17 and the unit attribute with a value of mph:
    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 of partly cloudy:
    customMetadataContent:"conditions.partly cloudy.conditions"
  • This query expression finds objects that have custom metadata that contains the date element with a value of 20121130:
    <![CDATA[customMetadataContent:"<date>20121130</date>"]]>
  • This query expression finds objects that have custom metadata that contains the temp_high element with a value of 31 and the unit attribute with a value of deg_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 and USER.

  • 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 includes all_users or authenticated, 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.

Specifying permissions

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"
NoteUsing 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.
aclGrant considerations

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 and authenticated, 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

  1. 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 earlier changeTimeMilliseconds end time until the count property in the response is no more than 100,000.

  2. 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 the count value in each request
    For example, the request body for the third iteration of the paged query might look like this:
    <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.
  3. Repeat step 1 above using a changeTimeMilliseconds entry that specifies a range with start value equal to the end value of the changeTimeMilliseconds range you used in step 2.

    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 a changeTimeMilliseconds value like this:
    changeTimeMilliseconds:{1150000000000.00 TO 1341000000000.00]

    Then repeat step 2 using the new query criteria.

  4. Repeat step 3 until you retrieve the last matching object.

    Use a value of * (for an unlimited range) as the end of the changeTimeMilliseconds 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.

EntryValid valuesDescription
count

One of:

  • -1, to request all operation records that meet the query criteria
  • A positive integer

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.

lastResultN/ASpecifies 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.
objectPropertiesA 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 verbose and objectProperties entries, HCP returns only the object URL, version ID, operation type, and change time and the information specified in the objectProperties entry.

systemMetadataN/ASpecifies the properties to use as the query criteria.
verbose

One of:

  • true

    Return all object properties.

  • false

    Return only the object URL, version ID, operation, and change time.

Specifies whether to return complete metadata for each operation record in the result set (true) or to return only the object URL, version ID, operation type, and change time (false).

The default is false.

If the query request body contains both the verbose and objectProperties entries, HCP returns only the object URL, version ID, operation type, and change time and the information specified in the objectProperties entry.

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.

EntryValid valuesDescription
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 suffixSpecifies the changeTimeMilliseconds value in the last operation record returned in response to the previous query.
versionA version IDSpecifies 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.

EntryValid valuesDescription
changeTimeN/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 start and end child entries.

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:

  • Milliseconds since January 1, 1970, 00:00:00 UTC.
  • An ISO 8601 datetime value in this format:

    yyyy-MM-ddThh:mm:ssZ

    Z represents the offset from UTC, in this format:

    (+|-)hhmm

    For example, 2011-11-16T14:27:20-0500 represents the start of the 20th second into 2:27 PM, November 16, 2011, EST.

Requests operation records for objects with change times on or after the specified date and time. This entry is a child entry of the changeTime entry.

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:

  • Milliseconds since January 1, 1970, 00:00:00 UTC
  • An ISO 8601 datetime value in this format:

    yyyy-MM-ddThh:mm:ssZ

Requests operation records for objects with change times before the specified date and time. This entry is a child entry of the changeTime entry.

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.

directoriesN/A

Specifies the directories to query. This entry contains zero or more directory entries.

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

rest, data, or fcfs_data. Do not include rest, data, or fcfs_data in the path.

Specifies a directory to query. This entry is a child of the directories entry.

If you query multiple namespaces, HCP returns operation records for the directory contents in each namespace in which the directory occurs.

indexable

One of:

  • true

    Return operation records only for objects with an index setting of true.

  • false

    Return operation records only for objects with index setting of false.

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.

namespacesN/A

Specifies the namespaces to query. This entry contains zero or more namespace entries.

If the URL in the request starts with default, you can omit this entry. The URL itself limits the query to the default namespace.

If you omit this entry and the URL starts with admin, HCP returns operation records for the default namespace and the namespaces owned by each tenant that has granted system-level users administrative access to itself.

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:

  • true

    Return operation records only for objects that are flagged as replication collisions.

  • false

    Return operation records only for objects that are not flagged as replication collisions.

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.

transactionsN/A

Specifies the operation types for which to query. This entry contains up to five transaction entries, each specifying a different operation type.

If you omit this entry, HCP returns records only for create, delete, and purge operations.

transaction(child)

One of:

  • create
  • delete
  • dispose
  • prune
  • purge

Specifies a type of operation for which to return records. This entry is a child entry of the transactions entry.

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 the urlName, changeTimeMilliseconds, and version 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 entry
  • sort 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 propertyData typeDescriptionQuery expression example
accessTimeLongThe 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 String1Datetime

The value of the POSIX atime attribute for the object, in ISO 8601 format:

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]
acl2Boolean

An indication of whether the object has an ACL. Valid values are:

  • true

    The object has an ACL.

  • false

    The object does not have an ACL.

This value is always false for objects in the default namespace.

acl:true
aclGrantString

ACL content.

This property can be used only in queries. It cannot be used in sort or objectProperties properties.

aclGrant:"Ww,USER,
europe,rsilver"
changeTime MillisecondsString

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 ctime attribute for the object.

changeTimeMilliseconds:
 [1311206400000.00 TO
1311292800000.00]
changeTime String1Datetime

The object change time in ISO 8601 format:

YYYY-MM-DDThh:mm:ssZ

For more information about this format, see the description of the accessTimeString property.

This property corresponds to the POSIX ctime attribute for the object.

changeTimeString:
[2012-03-21
T00:00:00 TO
2012-03-21
T23:59:59]
custom Metadata2Boolean

An indication of whether the object has custom metadata. Valid values are:

  • true

    The object has custom

  • false

    The object does not have custom metadata.

customMetadata:true
custom Metadata AnnotationStringOne or more comma-delimited annotation names. Annotation names are case-sensitive.
customMetadata
Annotation:inventory
custom Metadata ContentString

Custom metadata content.

This property can be used only in queries. It cannot be used in sort or objectProperties properties.

customMetadata
Content:city.Bath.
city
dplIntegerThe DPL for the namespace that contains the object.
dpl:2
gid3IntegerThe POSIX group ID.N/A
hash4String

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..."
hashScheme4String

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
hold2Boolean

An indication of whether the object is currently on hold. Valid values are:

  • true

    The object is on hold.

  • false

    The object is not on hold.

hold:false
index2Boolean

An indication of which parts of the object are indexed. Valid values are:

  • true

    All metadata, including any custom metadata and ACL, is indexed.

  • false

    Only system metadata and ACLs are indexed.

index:true
ingestTimeLongThe time at which HCP stored the object, in seconds since January 1, 1970, at 00:00:00 UTC.
ingestTime:[130947840
TO 1312156800]
ingestTime String1Datetime

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 accessTimeString property.

ingestTimeString:
[2012-03-01
T00:00:00
TO 2012-03-01
T23:59:59]
namespace2String

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
objectPath4String

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"
operation3String

The type of operation the result represents.

Possible values in a response body are:

  • CREATED
  • DELETED
  • DISPOSED
  • PRUNED
  • PURGED
  • NOT_FOUND

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 true in the verbose entry.

N/A
owner2String

For objects in HCP namespaces, the user that owns the object. Valid values are:

  • For objects that have an owner:
    USER,location,username
  • For objects with no owner:
    GROUP,location,all_users
  • For objects that existed before the HCP system was upgraded from a pre-5.0 release and that have not subsequently been assigned an owner:
    nobody

In these values:

  • location is the location in which the user account for the object owner is defined. This can be:
    • The name of an HCP tenant
    • The internal ID of an HCP tenant
    • An Active Directory domain preceded by an at sign (@)

    Internal IDs of HCP tenants are not returned in query results.

    For objects with no owner, location is the name of the tenant that owns the namespace in which the object is stored.

  • username is the name of the user that owns the object. This can be:
    • The username of a user account that’s defined in HCP.
    • The username of an Active Directory user account. This can be either the user principal name or the Security Accounts Manager (SAM) account name for the user account.

    This property is not returned for objects in the default namespace.

    If the Authorization header or hcp-ns-auth cookie identifies a tenant-level user, you can specify this criterion in a query expression to find all objects owned by that user:

    owner:USER
owner:"USER,europe,pdgrey"
owner2 (continued)String

These considerations apply when you specify the owner property in a query expression:

  • The entire value must be enclosed in double quotation marks.
  • USER, GROUP, and nobody are case sensitive.
  • The location values you specify are not case sensitive.
  • The username values you specify, except for all_users, are not case sensitive.
permissions3IntegerThe octal value of the POSIX permissions for the object.N/A
replicated3Boolean

An indication of whether the object has been replicated. Possible values in a response body are:

  • true

    The object, including the current version and all metadata, has been replicated.

  • false

    The object has not been replicated.

N/A
replication CollisionBoolean

An indication of whether the object is flagged as a replication collision. Valid values are:

  • true

    The object is flagged as a replication collision.

  • false

    The object is not flagged as a replication collision.

replicationCollision:true
retentionLong

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:

  • 0

    Deletion Allowed

  • -1

    Deletion Prohibited

  • -2

    Initial Unspecified

retention:"-1"
retentionClass4String

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 String1String

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 accessTimeString property.

This value can also be one of these special values:

  • Deletion Allowed
  • Deletion Prohibited
  • Initial Unspecified

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”
shred2Boolean

An indication of whether the object will be shredded after it is deleted. Valid values are:

  • true

    The object will be shredded.

  • false

    The object will not be shredded.

shred:true
sizeLongThe size of the object content, in bytes.
size:[2000 TO 3000]
type3StringThe object type. In a response body, this value is always object.N/A
uid3IntegerThe POSIX user ID.N/A
urlName3String

The fully qualified object URL. For example:

https://finance.europe.hcp.example.com/rest/Presentations/

Q1_2012.ppt

N/A
updateTimeLongThe 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 String1Datetime

The value of the POSIX mtime attribute for the object, in ISO 8601 format:

YYYY-MM-DDThh:mm:ssZ

For more information about this format, see the description of the accessTimeString property.

updateTimeString:
[2012-04-01
T00:00:00
TO 2012-04-30
T23:59:59]
utf8Name4String

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-name4Depends on property typeThe value of a content property.
doctor_name: "John Smith"
Notes:
  1. HCP maintains the time for this property as a value that includes millisecond, but the property format uses seconds. As a result, specifying a single datetime value for this property in a query does not return all expected results. To retrieve all expected results, take one of these actions:
    • Specify a range of values for this property.
    • Specify a value for the corresponding long-type object property. For example, instead of specifying ingestTimeString:2012-04-01T00:00:00, specify ingestTime:1333238400.
  2. You cannot specify a range of values for this property.
  3. For object-based queries, you can specify this property only in the objectProperties entry. If you specify this property in either the sort or query entry, HCP returns a 400 (Bad Request) error.
  4. You can use the asterisk (*) and question mark (?) wildcard characters when specifying values for this property.

 

  • Was this article helpful?