Class: Queries

Queries

new Queries(domain)

Parameters:
Name Type Description
domain string The project domain
Source:

Methods

compileQuery(query-path, token)

This method precompiles a query. If the specified query has already been precompiled, the precompiled query is updated.

Parameters:
Name Type Description
query-path string The query path. It starts with "public" or "private" and contains slashes.,
token string A project token.,
Source:

createQuery(query-path, token, compile, query-body)

This method creates a new query resource. If the compile option is none, the query will not be compiled, if it is lax it will be compiled and any potential compilation error reported. In this case, compilation errors will not prevent the query to be created. To only create the query if no compilation errors are present, set the compile option to strict. The default is none.

The query file extension must be either .jq or .xq.

Parameters:
Name Type Description
query-path string The query path. It starts with "public" or "private" and contains slashes.,
token string A project token.,
compile string The kind of compilation to perform. The default is none.,
query-body string The source code of the query,
Source:

executeQuery(Accept, query-path, format, token)

This method executes a query and serialize its results using a chosen serialization method. The following serialization methods are available: JSON-XML-hybrid, JSON, XML, Text, HTML, and XHTML.

It is also possible to use the 28.io serialization method. The 28.io serialization produces a JSON object with metadata about the items produced as query result. This serialization method format is unstable and will be documented as soon we are ready to commit to backward compatibility.

Query Serialization

If the query specifies the response content-type or encoding using the HTTP response module and the query execution completes without raising errors, its serialization method cannot be overridden through this api. Similarly, if the query specifies a response status code and the query execution completes without raising errors, the HTTP status code set by the query is systematically used as the response status code.

If the query does not specify a response content-type, the serialization method can be chosen by means of the Accept header or by specifying the format parameter. In case the query does not specify a response content-type and no serialization method is specified, JSON-XML-hybrid is used.

Specifically, the serialization method is chosen as follows:

  1. if an Accept header is specified and if it contains at least one supported mime-type/charset pair, the serialization method corresponding to the most preferred one (according to the "q" modifier first and the order in which the mime-types are specified second) among those supported is chosen;
  2. otherwise, if a format parameter is specified, the corresponding serialization method is chosen;
  3. otherwise, JSON-XML-hybrid is used.

If the Accept header is specified and it contains at least one supported mime-type, the preferred supported mime-type is used to choose the serialization method, according to the following mapping:

Any mime-type not matching one of the conditions listed above is not supported by this resource.

If the format parameter is used to choose the serialization method, the following mapping is used:

Response Content-Type and Encoding

The content-type of the response is determined as follows:

  1. If the query has set the response content-type, it will be used in the response. If this content-type, however, is not acceptable according to the Accept header specified in the request, an error will be raised and the response status code will be set to 406. Note that application/mixed-json-xml is treated as * / * when considering if the content-type set by the query is accepted or not.
  2. If the serialization method has been chosen depending on one of the mime-types specified in the Accept header, the following criterion are used:
    • if the used mime-type is * / * or application/mixed-json-xml then the response content type depends on the first item of the result. If it is an XML node the response content-type will be application/xml, otherwise application/json
    • for any other mime-type, the same mime-type is used in the response.
    In case no charset has been set by the query or specified for that mime-type in the Accept header, UTF-8 is used.
  3. If the serialization method has been chosen due to the format parameter or the query file extension the content-type of the response is chosen as follows:
    • JSON-XML-hybrid serialization: the response content type depends on the first item of the result. If it is an XML node the response content-type will be application/xml;charset=UTF-8, otherwise application/json;charset=UTF-8
    • JSON serialization: application/json;charset=UTF-8
    • XML serialization: application/xml;charset=UTF-8
    • Text serialization: text/plain;charset=UTF-8
    • HTML serialization: text/html;charset=UTF-8
    • XHTML serialization: application/xhtml+xml;charset=UTF-8
    • 28.io serialization: application/28io+json;charset=UTF-8

If the items produced by the query cannot be serialized using the chosen serialization method a 500 internal server error will be raised.

Parameters:
Name Type Description
Accept string Value of the Accept header.,
query-path string The query path. It starts with public or private and can contain slashes.,
format string The serialization method to use for the results of the executed query. When choosing a serialization method, this parameter has a lower priority than the Accept header.,
token string A project token.,
Source:

executeSimpleQuery(query-path, format, token)

This method executes a non-side-effecting query and serialize its results using a chosen serialization method. The following serialization methods are available: JSON-XML-hybrid, JSON, XML, Text, HTML, and XHTML.

It is also possible to use the 28.io serialization method. The 28.io serialization produces a JSON object with metadata about the items produced as query result. This serialization method format is unstable and will be documented as soon we are ready to commit to backward compatibility.

The HTTP response of this method is using streaming. Therefore, if an error occurs after part of the response has already been sent to the client, the response status code will be 200. In this case, the streaming of the HTTP response will stop and the following string will be sent "\n\n\nAn error occurred during the processing of the request.\n" followed by the error description. To always get a well-formed JSON error response, and the expected HTTP error status code, it is possible to issue the same request using POST. Note however that, in this case, the HTTP response will not stream.

Query Serialization

The serialization method can be chosen by means of the Accept header or by specifying the format parameter. In case no serialization method is specified, JSON-XML-hybrid is used.

Specifically, the serialization method is chosen as follows:

  1. if an Accept header is specified and if it contains at least one supported mime-type/charset pair, the serialization method corresponding to the most preferred one (according to the "q" modifier first and the order in which the mime-types are specified second) among those supported is chosen;
  2. otherwise, if a format parameter is specified, the corresponding serialization method is chosen;
  3. otherwise, JSON-XML-hybrid is used.

If the Accept header is specified and it contains at least one supported mime-type, the preferred supported mime-type is used to choose the serialization method, according to the following mapping:

Any mime-type not matching one of the conditions listed above is not supported by this resource.

If the format parameter has been specified and is used to choose the serialization method, the following mapping is used:

Response Content-Type and Encoding

The content-type of the response is determined as follows:

  1. If the serialization method has been chosen depending on one of the mime-types specified in the Accept header, the following criterion are used:
    • if the used mime-type is * / * or application/mixed-json-xml then the response content type depends on the first item of the result. If it is an XML node the response content-type will be application/xml, otherwise application/json
    • for any other mime-type, the same mime-type is used in the response.
    In case no charset has been specified for that mime-type in the Accept header, UTF-8 is used. Otherwise, the specified charset is used.
  2. If the serialization method has been chosen due to the format parameter or the query file extension the content-type of the response is chosen as follows:
    • JSON-XML-hybrid serialization: the response content type depends on the first item of the result. If it is an XML node the response content-type will be application/xml;charset=UTF-8, otherwise application/json;charset=UTF-8
    • JSON serialization: application/json;charset=UTF-8
    • XML serialization: application/xml;charset=UTF-8
    • Text serialization: text/plain;charset=UTF-8
    • HTML serialization: text/html;charset=UTF-8
    • XHTML serialization: application/xhtml+xml;charset=UTF-8
    • 28.io serialization: application/28io+json;charset=UTF-8

If any of the items produced by the query cannot be serialized using the chosen serialization method a 500 internal server error will be raised.

Parameters:
Name Type Description
query-path string The query path. It starts with public or private and can contain slashes.,
format string The serialization method to use for the results of the executed query. When choosing a serialization method, this parameter has a lower priority than the Accept header.,
token string A project token.,
Source:

getQuery(query-path, token)

This method retrieves the source code of a query. The response content-type is set according to the query language. If the query does not declare its own dialect, the query file extension is used to infer the language of the query. If the query file extension is .xq the query language is considered to be XQuery, JSONiq, otherwise.

Parameters:
Name Type Description
query-path string The query path. It starts with "public" or "private" and contains slashes.,
token string A project token.,
Source:

getQueryPlan(query-path, token)

This method retrieves the execution plan of a query.

Parameters:
Name Type Description
query-path string The query path. It starts with "public" or "private" and contains slashes.,
token string A project token.,
Source:

listQueries(visibility, token)

This method retrieves a list of queries that belong to a project. To only list public (resp. private) queries set the visibility parameter to public (resp. private). To list both public and private queries, omit the visibility parameter.

Parameters:
Name Type Description
visibility string The query visibility.,
token string A project token.,
Source:

removeQuery(query-path, token)

This method removes a query.

Parameters:
Name Type Description
query-path string The query path. It starts with "public" or "private" and contains slashes.,
token string A project token.,
Source:

saveQuery(query-path, token, compile, query-body, Content-Type)

This method updates the source code of an existing query. If the compile option is none, the query will not be compiled, if it is lax it will be compiled and any potential compilation error reported. In this case, compilation errors will not prevent the query to be created or updated. To only create the query if no compilation errors are present, set the compile option to strict. The default is none.

The query file extension must be either .jq or .xq.

Parameters:
Name Type Description
query-path string The query path. It starts with "public" or "private" and contains slashes.,
token string A project token.,
compile string The kind of compilation to perform. The default is none.,
query-body string The query source code,
Content-Type string ,
Source: