Skip to main content
Hitachi Vantara Knowledge

Query requests


This chapter describes how to construct both object-based and operation-based query requests.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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.

For information on request URL formats, see Request URL.

Optionally, if the URL starts with an IP address, an HTTP Host header.

For information on specifying the HTTP Host header, see Connecting using an IP address.

An Authorization header.

For information on the Authorization header, see Authentication.

An HTTP Content-Type header with one of these values:

oIf the request body is XML, application/xml

oIf 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:

oAn HTTP Content-Encoding header with a value of gzip

oA chunked transfer encoding

NoteWebHelp.png

Note: When 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.

For more information on the request body for object-based queries, see Object-based query requests. For more information on the request body for operation-based queries, see Operation-based query requests.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Object-based query requests


The body of an object-based query request consists of entries in XML or JSON format.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

XML request body for object-based queries


The XML request body for an object-based query must contain a top-level queryRequest entry, an object entry, and a query entry. All other entries are optional.

The XML request body for an object-based query has the format shown below. The entries under object can be specified in any order.

<queryRequest>
    <object>
         <query>
query-expression</query>
         <contentProperties>
(true|false)</contentProperties>
         <count>
number-of-results</count>
        <facets>
comma-separated-list-of-facets</facets>
         <objectProperties>
comma-separated-list-of-properties
         </objectProperties>
        <offset>
number-of-results-to-skip</offset>
        <sort>
object-property[+(asc|desc)][,.object-property
            [+(asc|desc)]]....</sort>
        <verbose>
(true|false)</verbose>
    </object>
</queryRequest>

For a complete list of object properties, see Object properties.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

JSON request body for object-based queries


The JSON request body for an object-based query must contain an unnamed top-level entry, an object entry, and a query entry. All other entries are optional.

The JSON request body for an object-based query has the format shown below. The entries under object can be specified in any order.

{
    "object":{
        "query":"query-expression",
        "contentProperties":"(true|false)",
        "count":number-of-results,
        "facets":"comma-separated-list-of-facets",
        "objectProperties":"comma-separated-list-of-properties",
        "offset":number-of-results-to-skip,
        "sort":"object-property[+(asc|desc)][,.object-property
            [+(asc|desc)]]..."
        "verbose":"(true|false)"
    }
}

For a complete list of objectProperty values, see Object properties.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Request object body contents


The following sections describe the entries in an object-based metadata query API request body.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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.

For more information on query expressions, see Query expressions.

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.

For more information on this entry, see facets entry.

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.

For a list of object properties, see Object properties.

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.

For information on performing paged queries, see Paged queries with object-based requests.

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.

For more information on this entry, see sort entry.

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.

For information on the returned properties, see Object properties.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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.

For information on the object properties on which you can sort query results, see Object properties.

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.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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 table below. Multiple properties can be specified in any order.

Object property

Description

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 information on specifying ranges for numeric and date content properties, see Content property facet ranges below.

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:

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

oPrecede the time interval with a plus sign (+).

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

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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.

TipWebHelp.png

Tip: You 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 on the Show as advanced query link. The resulting advanced query can be used as a query expression in an object-based query request.

For information on constructing structured queries with the Metadata Query Engine Console, see Searching Namespaces.

For information on the criteria you can specify in query expressions, see Text-based criteria and Property-based criteria. For information using criteria to construct query expressions, see Query expression considerations. For more information on the query language used to construct query expressions, see the Apache Solr documentation at http://lucene.apache.org/solr/documentation.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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. For information on property-based criteria, see 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 left is valid; the query expression on the right 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

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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.

For information on:

The object properties and values you can use in property-based criteria, see Object properties.

Specifying the property value when you query for an object path, custom metadata content, or a content property with the tokenized data type, see Text-based criteria.

The property you use to query for objects based on the content of ACLs, see aclGrant property.

The property you use to query for objects based on the full-text content of custom metadata, see customMetadataContent property.

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}

NoteWebHelp.png

Note: utf8Name 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 left is valid; the query expression on the right is not:

Valid: utf8Name:princ*       Invalid: utf8Name:*cipal

For information on using wildcards with objectPath and customMetadataContent properties and for content properties with the Tokenized data type, see Text-based criteria.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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. Therefore, the rules described in Text-based criteria apply to the property value.

TipWebHelp.png

Tip: If 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. For information on specifying these wildcards, see Text-based criteria.

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

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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 is one or more of these with no space between them:

oR — Read_ACL

or — Read

oW — Write_ACL

ow — Write

od — 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. For information on specifying permissions, see Specifying permissions below.

USER is 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 is required when querying for objects with ACLs that grant permissions to a specific group of users.

location is the location in which the specified user or group is defined. Valid values are either:

oThe name of an HCP tenant

oThe 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 is the name of a user to which matching ACLs grant the specified permissions. Valid values are:

oThe username for a user account that’s defined in HCP.

oThe username 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 is 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"

NoteWebHelp.png

Note: Using 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.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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:

oIf the value is INCOMPLETE, more results remain. Request another page.

oIf the value is COMPLETE, the result set includes the last object that meets the query criteria.

For information on handling paged queries with 100,000 or fewer matching objects, see Paged queries with 100,000 or fewer matching objects. For information on handling requests with very large numbers of matching objects, see Paged queries with more than 100,000 matching objects.

For an example of using a paged object-based query, see Example 2: Using a paged query to retrieve a list of all objects in a namespace.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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:

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:

o A changeTimeMilliseconds criterion that specifies the same time as you used in the last request in step 1

oA count entry value that specifies the number of objects you want per page

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

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Operation-based query requests


The body of an operation-based query request consists of entries in XML or JSON format.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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/>

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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:

{}

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

Request operation body contents


The following sections describe the entries in an operation-based metadata query API request body.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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:

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

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.

For descriptions of the child entries, see lastResult entry. For more information on paged queries, see paged queries with operation-based requests.

object
  Properties

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

For a list of object properties, see Object properties.

systemMetadata

N/A

Specifies the properties to use as the query criteria. For descriptions of the child entries, see systemMetadata entry.

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.

For information on the returned properties, see Object properties.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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.

For more information on this entry, seeObject properties.

version

A version ID

Specifies the version value in the last operation record returned in response to the previous query.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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

directories

N/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.

namespaces

N/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.

For information on considerations that apply when you specify this entry, see Queries specified namespaces.

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.

transactions

N/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.

For more information on operation types, see Object-based queries.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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:

oIf the value is INCOMPLETE, more results remain. Request another page.

oIf the value is COMPLETE, the result set includes the last object that meets the query criteria.

For an example of using a paged operation-based query, see Example 3: Using a paged query to retrieve a large number of records.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

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

acl2

Boolean

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

aclGrant

String

ACL content.

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

For more information on this property, see aclGrant property.

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 on 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
String1

Datetime

The object change time in ISO 8601 format:

YYYY-MM-DDThh:mm:ssZ

For more information on 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
Metadata2

Boolean

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

true — The object has custom metadata.

false — The object does not have custom metadata.

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 sort or objectProperties properties.

For more information on this property, see customMetadataContent property.

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:

true — The object is on hold.

false — The object is not on hold.

hold:false

index2

Boolean

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

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 on this format, see the description of the accessTimeString property.

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.

For considerations that apply when you specify this property in a query expression, see Queries specified namespaces.

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:

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

owner2

String

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:

oThe name of an HCP tenant

oThe internal ID of an HCP tenant

oAn 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:

oThe username of a user account that’s defined in HCP.

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

 

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:

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

false — The object has not been replicated.

N/A

replication
Collision

Boolean

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

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:

0 Deletion Allowed

-1 Deletion Prohibited

-2 Initial Unspecified

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

shred2

Boolean

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

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.c...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 mtime attribute for the object, in ISO 8601 format:

YYYY-MM-DDThh:mm:ssZ

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

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

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.

© 2015, 2019 Hitachi Vantara Corporation. All rights reserved.

 

  • Was this article helpful?