18    Scope Specification

18.1   Introduction

CDMI™ provides a standardized mechanism to define sets of objects that match certain characteristics. This mechanism is known as a CDMI scope specification. Scope specifications are typically used to provide a CDMI client with a way to indicate in what set of CDMI objects it is interested.

Each JSON object within the scope specification represents a set of conditions that shall all be true in order for an object to be considered to match against the scope (a logical AND relationship). For queries, a matching object would be returned in the query results. An empty scope specification is considered to evaluate to true. Multiple JSON objects are used to express logical OR relationships, where if any JSON object in the scope evaluates to true, then the object shall be considered to have matched against the scope.

Each JSON object is constructed using the same structure that CDMI objects use. To show this structure, assume the following result from a CDMI GET for a data object:

HTTP/1.1 200 OK

Content-Type: application/cdmi-object

X-CDMI-Specification-Version: 1.0.2

 

{

   "objectType" : "application/cdmi-object",

   "objectID" : "00007E7F0010EB9092B29F6CD6AD6824",

   "objectName" : "MyDataObject.txt",

   "parentURI" : "/MyContainer/",

     "parentID" : "00007E7F00102E230ED82694DAA975D2",

   "domainURI" : "/cdmi_domains/MyDomain/",

   "capabilitiesURI" : "/cdmi_capabilities/dataobject/",

   "completionStatus" : "Complete",

   "mimetype" : "text/plain",

   "metadata" : {

      "cdmi_size" : "108263"

   },

   "valuerange" : "0-108262",

   "value" : "..."

}

18.2   Examples

Each field inside a scope specification JSON object represents a condition that shall be met for a field.

EXAMPLE 1   A query to find all objects belonging to the domain /cdmi_domains/MyDomain/ is structured as follows:

[

   {

       "domainURI" : "== /cdmi_domains/MyDomain/"

   }

]

EXAMPLE 2   To query for all objects belonging to the domain /cdmi_domains/MyDomain/ AND are also located within the container MyContainer, the scope specification is structured as follows:

[

   {

       "parentURI" : "== /MyContainer/",

       "domainURI" : "== /cdmi_domains/MyDomain/"

   }

]

EXAMPLE 3   To query for all objects that belong to the domain MyDomain OR are located within the container MyContainer, the query is structured as follows:

[

   {

       "parentURI" : "== /MyContainer/",

   },

   {

       "domainURI" : "== /cdmi_domains/MyDomain/"

   }

]

Queries may match on any field within an object that a cloud storage system is capable of returning as a result of an object GET.

EXAMPLE 4   To query metadata items, the metadata object is included as an object within the query request. This query is shown as follows:

[

   {

       "metadata" : {

           "colour" : "== blue"

       }

   }

]

This approach allows matching against arbitrarily nested metadata structures.

To query the value of objects, the value field is included within the query request. Values are always represented using base 64 encoding in queries.

EXAMPLE 5   This query is shown as follows:

{

  [

      {

          "value": "== Ymx1ZQ=="

      }

  ]

}

Query against the value of objects is optional and is indicated by the presence of the cdmi_query_value capability.

18.3   Query Matching Expressions

Table 119 defines the query matching expressions.

Table 119 - Query Matching Expressions

Matching Expression

Description

"field" : "*"

The exists matching expression tests for the existence of the field. If the field is present, even if empty, the condition shall be considered to be met.

"field" : "!*"

The not exists matching expression tests for the non-existence of the field. If the field is absent, the condition shall be considered to be met.

"field" : "== constant"

The equals matching expression tests for the equality of the value of the field and a specified constant value. The equality test is case sensitive.

The leading space after the "==" and before the constant value is not included in the comparison. If the constant value matches the value of the field, the condition shall be considered to be met.

If the matching expression starts with a "#" character (e.g., "#=="), the value of the field is considered to be numeric for the purposes of comparison. Numeric constant strings shall be processed according to the JSON number representation described in RFC 4627. A numeric matching expression shall be considered to be non-matching against a non-numeric field value.

"field" : "!= constant"

The not equals matching expression tests for the non-equality of the value of the field and a specified constant value. The not-equals test is case sensitive.

The leading space character after the "!=" and before the constant value is not included in the comparison. If the constant value does not match the value of the field, the condition shall be considered to be met.

If the matching expression starts with a "#" character (e.g., "#!="), the value of the field is considered to be numeric for the purposes of comparison. Numeric constant strings shall be processed according to the JSON number representation described in RFC 4627. A numeric matching expression shall be considered to be non-matching against a non-numeric field value.

"field" : "> constant"

The greater than matching expression tests if the value of the field is lexicographically greater than a specified constant value. The greater than test is case sensitive.

The leading space character after the ">" and before the constant value is not included in the comparison.

If the constant value is greater than the value of the field, the condition shall be considered to be met. If the matching expression starts with a "#" character (e.g., "#>"), the value of the field is considered to be numeric for the purposes of comparison. Numeric constant strings shall be processed according to the JSON number representation described in RFC 4627. A numeric matching expression shall be considered to be non-matching against a non-numeric field value.

"field" : ">= constant"

The greater than or equals to matching expression tests if the value of the field is lexicographically greater than or equal to a specified constant value. The greater than or equals to test is case sensitive.

The leading space character after the ">=" and before the constant value is not included in the comparison.

If the constant value is greater than or equal to the value of the field, the condition shall be considered to be met. If the matching expression starts with a "#" character (e.g., "#>="), the value of the field is considered to be numeric for the purposes of comparison. Numeric constant strings shall be processed according to the JSON number representation described in RFC 4627. A numeric matching expression shall be considered to be non-matching against a non-numeric field value.

"field" : "< constant"

The less than operator tests if the value of the field is lexicographically less than a specified constant value. The less than test is case sensitive.

The leading space character after the "<" and before the constant value is not included in the comparison.

If the constant value is less than the value of the field, the condition shall be considered to be met. If the matching expression starts with a "#" character (e.g., "#<"), the value of the field is considered to be numeric for the purposes of comparison. Numeric constant strings shall be processed according to the JSON number representation described in RFC 4627. A numeric matching expression shall be considered to be non-matching against a non-numeric field value.

"field" : "<= constant"

The less than or equals to matching expression tests if the value of the field is lexicographically less than or equal to a specified constant value. The less than or equal test is case sensitive.

The leading space character after the "<=" and before the constant value is not included in the comparison.

If the constant value is less than or equal to the value of the field, the condition shall be considered to be met. If the matching expression starts with a "#" character (e.g., "#<="), the value of the field is considered to be numeric for the purposes of comparison. Numeric constant strings shall be processed according to the JSON number representation described in RFC 4627. A numeric matching expression shall be considered to be non-matching against a non-numeric field value.

"field" : "starts constant"

The starts with matching expression tests if the field value starts with a specified constant value. The leading space character after the "starts" and before the constant value is not included in the comparison. The starts with test is case sensitive.

If the constant value is equal to the start of the value of the field, the condition shall be considered to be met.

"field" : "!starts constant"

The not starts with matching expression tests if the field value does not start with a specified constant value. The leading space character after the "!starts" and before the constant value is not included in the comparison. The not starts with test is case sensitive.

If the constant value is not equal to the start of the value of the field, the condition shall be considered to be met.

"field" : "ends constant"

The ends with matching expression tests if the field value ends with a specified constant value. The leading space character after the "ends" and before the constant value is not included in the comparison. The ends with test is case sensitive.

If the constant value is equal to the end of the value of the field, the condition shall be considered to be met.

"field" : "!ends constant"

The not ends with matching expression tests if the field value does not end with a specified constant value. The leading space character after the "!ends" and before the constant value is not included in the comparison. The not ends with test is case sensitive.

If the constant value is not equal to the end of the value of the field, the condition shall be considered to be met.

"field" : "contains constant"

The contains matching expression tests if the field value contains a specified constant value. The leading space character after the "contains" and before the constant value is not included in the comparison. The contains test is case sensitive.

If the constant value is found as a substring within the value of the field, the condition shall be considered to be met. The contains operator is only supported if the cdmi_query_contains capability is present.

"field" : "!contains constant"

The not contains matching expression tests if the field value does not contain a specified constant value. The leading space character after the "!contains" and before the constant value is not included in the comparison. The not contains test is case sensitive.

If the constant value is not found as a substring within the value of the field, the condition shall be considered to be met. The not contains operator is only supported if the cdmi_query_contains capability is present.

"field" : "tag constant"

The tag matching expression tests if the field value contains a specified constant tag value. The leading space character after the "tag" and before the constant value is not included in the comparison. The tag test is not case sensitive.

If the constant value is found as a tag substring within the value of the field, the condition shall be considered to be met. Tag substrings start at the beginning of the value or a ",", and end at the next "," or the end of the string. Whitespace before and after "," characters shall be stripped for the purpose of comparisons.

Tag matching expressions are only supported if the cdmi_query_tags capability is present.

"field" : "!tag constant"

The not tag matching expression tests if the field value does not contain a specified constant tag value. The leading space character after the "!tag" and before the constant value is not included in the comparison. The not tag test is not case sensitive.

If the constant value is not found as a tag substring within the value of the field, the condition shall be considered to be met. Tag substrings start at the beginning of the value or a ",", and end at the next "," or the end of the string. Whitespace before and after "," characters shall be stripped for the purpose of comparisons.

Tag matching expressions are only supported if the cdmi_query_tags capability is present.

"field" : "=~ constant"

The regular expression matching expression tests if the field value matches a specified constant regular expression value.

The leading space character after the "=~" and before the constant value is not included in the comparison. If the regular expression evaluates to true against the value, the condition shall be considered to be met.

Regular expression strings shall be processed according to the POSIX Extended Regular Expression (ERE) standard, as specified in IEEE Std 1003.1.

Regex matching expressions are only supported if the cdmi_query_regex capability is present.

"field" : "!~ constant"

The not regular expression matching expression tests if the field value does not match a specified constant regular expression value.

The leading space character after the "!~" and before the constant value is not included in the comparison. If the regular expression evaluates to false against the value, the condition shall be considered to be met.

Regular expression strings shall be processed according to the POSIX Extended Regular Expression (ERE) standard, as specified in The Open Group Base Specifications Issue 6, IEEE Std 1003.1, 2004 Edition.

Regex matching expressions are only supported if the cdmi_query_regex capability is present.

All fields in objects that are not included in the scope specification shall be ignored for the purpose of matching objects.

When a URI is used as the constant for the equals and not equals operators against the parentURI, domainURI, and capabilitiesURI, either a URI by path or URI by object ID can be specified and are considered interchangeable.

EXAMPLE 1   In a query to find all objects belonging to a specific domain, the following two query scopes are considered identical:

[

   {

        "domainURI" : "== /cdmi_domains/MyDomain/"

    }

]

and

[

   {

        "domainURI" : "== /cdmi_objectid/00007E7F001074C86AD256DA5C67180D/"

    }

]

EXAMPLE 2   Likewise, a query to find all objects with a given parent container would have two equivalent forms:

[

   {

        "parentURI" : "== /MyContainer/"

    }

]

and

[

   {

        "parentURI" : "== /cdmi_objectid/0000706D0010B84FAD185C425D8B537E/"  

    }

]

If an object ID is used in a query scope in the objectID field or the parentID field, all object IDs shall be processed such that they are case insensitive.