MarkLogic Server 11.0 Product Documentation
POST /v1/rows/graphql

Summary

Execute a GraphQL query in order to retrieve a JSON object with the results. The query is passed in the "query" property of the JSON request body.

URL Parameters
trace*	The name of a trace event to enable during this operation. Trace event output goes into the server log.
output?	Specify the form of output. Allowed values: `object`, `explain` (return explain output from a plan). Default: `object`.
timestamp?	A timestamp returned in the `ML-Effective-Timestamp` header of a previous request. Use this parameter to fetch results based on the database contents at a fixed point-in-time. For more details, see Performing Point-in-Time Operations in the REST Application Developer's Guide.
database?	Perform this operation on the named content database instead of the default content database associated with the REST API instance. Using an alternative database requires the "eval-in" privilege; for details, see Security Requirements in the REST Application Developer's Guide.

Request Headers
Accept*	The expected MIME type of the response. The only permitted value is `application/json`.
Content-type	Required. The MIME type of the request and is always `application/graphql`.

Response Headers
Content-type	The MIME type of the data in the response body. The MIME type corresponds to the type requested by the Accept header. A `charset=utf-8` declaration is appended to the response MIME type which is always `application/json`.
ML-Effective-Timestamp	The system timestamp at which this operation was performed. You can use the value in the `timestamp` parameter of a subsequent request. For more details, see Performing Point-in-Time Operations in the REST Application Developer's Guide.

Response

Upon success, MarkLogic Server returns status 200 (OK) and the response body contains the requested data.

Required Privileges

This operation requires the rest-reader role, or the following privilege:

http://marklogic.com/xdmp/privileges/rest-reader

Using the trace parameter requires the rest-tracer role, or the following privilege:

http://marklogic.com/xdmp/privileges/rest-tracer

Usage Notes

The request body must contain the JSON representation of a GraphQL request including a "query" property with the GraphQL query string. For more details, see POST requests in the GraphQL documentation.

The automatically generated implicit GraphQL schemas are based on schemas and views defined within the database. The default name of a query for a view in a schema is schemaName_viewName. So for the "employees" view in the "corporate" schema, the default query name would be "corporate_employees".

When the output parameter value is object, MarkLogic returns a JSON object with result data and/or error information. For more details, see the GraphQL HTTP specification.

Note that, per the GraphQL specification, a GraphQL GET request should simply have the query string as the parameter. However, this endpoint expects a JSON object with the GraphQL request just like a POST request.

Example

Basic Query Example
Suppose a TDE template defines an "employees" view in the "corporate" schema with the columns "name", "birthdate", and "title" for the Documents database, then a GraphQL query string might be: "query employeesQuery { corporate_employees { employeeNumber name birthdate title } }"
For that query, the JSON body of the request would be:
{
    "query": "query employeesQuery { corporate_employees { employeeNumber name birthdate title } }"
}

The following cURL command would send this request:
curl --anyauth --user user:password --request POST 'http://localhost:8000/v1/rows/graphql' --header 'Content-type: application/graphql' \
    --data-raw '{ "query": "query employees { corporate_employees { employeeNumber name birthdate title } }" }'

And the response would look something like the following:
{
    "data": {
        "corporate_employees": [
            {
                "employeeNumber": 1
                "name": "Joe Worker",
                "birthdate": "07/04/1995",
                "title": "Senior Widget Maker"
            },{
                "employeeNumber": 2
                "name": "Jane Supervisor",
                "birthdate": "11/02/1999",
                "title": "Chief Widget Officer"
            }
         ]
    }
}