22    Query Queues

22.1   Overview

A cloud storage system may optionally implement metadata and/or full-text query functionality. The implementation of query is indicated by the presence of the cloud storage system-wide capabilities for query and requires support for CDMI™ queues.

Query queues allow CDMI clients to efficiently discover what content matches a given set of metadata query criteria or full-content search criteria. Clients create or update a query queue by specifying metadata that defines the matching criteria (known as the query scope), along with what results should be returned for matching objects (known as the query results). The CDMI offering shall then perform the query using the content existing at the time the query is being processed, storing the query results in the query queue. As query results are found, they are added to the queue, and when the query is complete, the cdmi_query_status metadata of the queue is changed to indicate that the query has completed. Any matching objects created or modified while the query is being performed may or may not be included in the query results (e.g., as a consequence of eventual consistency).

When a client wishes to perform queries, it may first check if the system is capable of providing query functionality by checking for the presence of the cdmi_query capability in the root container capabilities. If this capability is not present, creating a query queue shall be successful, but no query results shall be enqueued into the query queue.

When creating a query queue, the metadata described in Table 124 shall be provided. Attempts to alter metadata in this table shall result in an HTTP status code of 403 Forbidden. After a query queue has been created, with the exception of cdmi_queue_type, the metadata items in this table cannot be changed. If the value of cdmi_queue_type is changed from "cdmi_query_queue", this change indicates to the system that an in-process query shall be stopped, the query queue shall no longer receive query results, and the query queue shall be treated as a regular CDMI queue object. To start a new query with an existing queue, the value of the cdmi_queue_type shall be changed back to "cdmi_query_queue". This international standard does not define a mechanism to pause a running query or resume a stopped query.

Table 124 - Required Metadata for a Query Queue

Metadata Name

Type

Description

Requirement

cdmi_queue_type

JSON String

The queue type indicates how the cloud storage system shall manage the queue object. The type of cdmi_query_queue is defined for query queues.

Mandatory

cdmi_scope_specification

JSON Array of JSON Objects

The scope specification determines which objects are included in the query results. This is equivalent to a "WHERE" clause in SQL-like languages. To query all objects, specify an empty JSON array. See Clause 18 for how to construct a scope specification.

Mandatory

cdmi_results_specification

JSON Object

Contains the JSON fields to be returned for each object that matches the query. This is equivalent to a "SELECT" clause in SQL-like languages. See Clause 19 for how to construct a results specification.

Mandatory

 

EXAMPLE 1   An example of the metadata associated with a query queue is as follows:

{

   "metadata" : {

       "cdmi_queue_type" : "cdmi_query_queue",

       "cdmi_scope_specification" : [

           {

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

               "parentURI" : "starts /sandbox",

               "metadata" : {

                   "cdmi_size" : "#> 100000"

                }

            }

       ],

       "cdmi_results_specification" : {

           "objectID" : "",

           "metadata" : {

                "cdmi_size" : ""

            }

        }

   }

}

When results are stored in a query queue, each enqueued value shall consist of a JSON object of MIME type "application/json". This JSON object contains the specified values requested in the cdmi_results_specification of the query queue metadata.

EXAMPLE 2   An example of a query result JSON object is as follows:

{

   "objectID" : "00007E7F0010EB9092B29F6CD6AD6824",

   "metadata" : {

        "cdmi_size" : "108263"

    }

}

Table 125 describes the system-created metadata that provides details on the status of the query queue.

Table 125 - Query Status Metadata

Metadata Name

Type

Description

Requirement

cdmi_query_status

JSON String

When present, this metadata item indicates the state of the query queue. Defined values are:

   Processing - Indicates that the query queue is scanning for results;

   Halted - Indicates that new query results will no longer be enqueued;

   Current - Indicates that the query queue contained all query results that can be found at this time; and

   Error - Indicates that the query queue metadata was not valid, or other errors were encountered that prevented all query results from being enqueued. Arbitrary vendor-defined text may follow the string "Error".

Mandatory

Objects shall only be included in the query results if the user who created the query queue is able to read the matching objects or metadata. For example, if the administrator created the query queue, then all matching objects that the administrator is allowed to read are included in the results. If user "jdoe" created the query queue, then only matching objects that "jdoe" is allowed to read are included in the results.

22.2   Extending CDMI Query

An implementor of a CDMI server may extend CDMI query by adding vendor-specific matching expressions. When an implementor adds vendor-specific metadata fields, these fields shall be queried using the standard query queue functionality.

An implementor of a CDMI server may extend CDMI query by allowing the creation of vendor-specific query queues with a type other than cdmi_query_queue.