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 isnone
, the query will not be compiled, if it islax
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 thecompile
option tostrict
. The default isnone
.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 theformat
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:
- 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; - otherwise, if a
format
parameter is specified, the corresponding serialization method is chosen; - 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:
application/mixed-json-xml
: JSON-XML-hybrid Serializationapplication/json
or any mime-type which ends with+json
: JSON Serializationtext/xml
,application/xml
or any mime-type which ends with+xml
: XML Serializationtext/html
: HTML Serializationapplication/xhtml+xml
: XHTML Serializationapplication/28io+json
: 28.io Serialization (format definition unstable)* / *
: theAccept
header is ignored and the format parameter, if specified, is used to choose the serialization method.
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:
.mixed
: JSON-XML-hybrid Serialization.json
: JSON Serialization.xml
: XML Serialization.text
: Text Serialization.html
: HTML Serialization.xhtml
: XHTML Serialization.28io-json
: 28.io Serialization (format definition unstable).
Response Content-Type and Encoding
The content-type of the response is determined as follows:
- 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 to406
. Note thatapplication/mixed-json-xml
is treated as* / *
when considering if the content-type set by the query is accepted or not. - 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
* / *
orapplication/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 beapplication/xml
, otherwiseapplication/json
- for any other mime-type, the same mime-type is used in the response.
Accept
header,UTF-8
is used. - if the used mime-type is
- 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
, otherwiseapplication/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
- 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
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
orprivate
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:
- if an
-
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 theformat
parameter. In case no serialization method is specified, JSON-XML-hybrid is used.Specifically, the serialization method is chosen as follows:
- 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; - otherwise, if a
format
parameter is specified, the corresponding serialization method is chosen; - 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:
application/mixed-json-xml
: JSON-XML-hybrid Serializationapplication/json
or any mime-type which ends with+json
: JSON Serializationtext/xml
,application/xml
or any mime-type which ends with+xml
: XML Serializationtext/html
: HTML Serializationapplication/xhtml+xml
: XHTML Serializationapplication/28io+json
: 28.io Serialization (format definition unstable)* / *
: theAccept
header is ignored and the format parameter, if specified, is used to choose the serialization method.
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:
.mixed
: JSON-XML-hybrid Serialization.json
: JSON Serialization.xml
: XML Serialization.text
: Text Serialization.html
: HTML Serialization.xhtml
: XHTML Serialization.28io-json
: 28.io Serialization (format definition unstable).
Response Content-Type and Encoding
The content-type of the response is determined as follows:
- 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
* / *
orapplication/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 beapplication/xml
, otherwiseapplication/json
- for any other mime-type, the same mime-type is used in the response.
Accept
header,UTF-8
is used. Otherwise, the specified charset is used. - if the used mime-type is
- 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
, otherwiseapplication/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
- 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
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
orprivate
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:
- if an
-
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 beXQuery
,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 topublic
(resp.private
). To list both public and private queries, omit thevisibility
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 isnone
, the query will not be compiled, if it islax
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 thecompile
option tostrict
. The default isnone
.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: