19    Results Specification

19.1   Introduction

CDMI™ provides a standardized mechanism to define subsets of object contents. This mechanism is known as a CDMI results specification. Results specifications are typically used to provide a CDMI client with a way to indicate on what subset of the contents of CDMI objects it intends to retrieve or operate.

Each JSON object within the results specification represents a set of fields that are returned for each matching object.

The results JSON object shall be constructed using the same structure as is used for CDMI objects. To show this, 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" : "..."

}

19.2   Examples

Each field inside a results specification JSON object indicates that the field shall be included in the results.

EXAMPLE 1   The following results specification requests that the objectID and cdmi_size metadata fields be returned in the results:

{

   "cdmi_results_specification" : {

       "objectID" : "",

       "metadata" : {

            "cdmi_size" : ""

        }

    }

}

EXAMPLE 2   If an object is matched, the result JSON is enqueued as follows:

{

   "objectID" : "00007E7F0010EB9092B29F6CD6AD6824",

   "metadata" : {

        "cdmi_size" : "108263"

    }

}

For most common use cases, clients request either the objectID, the objectName and parentURI, or all three fields in the cdmi_results_specification. If the parentURI or objectName is requested, the field shall only be returned for objects existing in a container object.

EXAMPLE 3   To request all metadata items be returned for each matching object, the following cdmi_results_specification shall be used:

{

   "cdmi_results_specification" : {

        "metadata" : ""

    }

}

EXAMPLE 4   To request all fields and all metadata items be returned for each matching object, the following cdmi_results_specification shall be used:

{

    "cdmi_results_specification" : ""

}  

The value field is always returned in base 64 encoding when included in a query result, where the valuetransferencoding field indicates the encoding that should be expected if a GET to read the object is performed.