Query HTTP API endpoint

Execute an FQL transaction.

curl -X POST \
  'https://db.fauna.com/query/1' \
  -H 'Authorization: Bearer $FAUNA_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"query": "Product.where(.price > 6_50)"}'

Request

Content-Type: application/json

Schema

Query

Field name Type Required Description

query

string

Yes

FQL transaction to be executed.

arguments

object

Object with values provided to the submitted transaction as variables. Note that variable names must be valid FQL identifiers.

The format is defined by the x-format header:

  • xformat = simple: A value when the format is set to simple.
    Example: (nullable: true)

  • xformat = tagged: One of the tagged format literals. See Tagged format argument literals.

Tagged format argument literals:

Literal Type Description

@int

string

32-bit signed integer

@long

string

64-bit signed integer

@double

string

64-bit double

[…​]

array

Array of values

{…​}

object

Object. Properties with a name starting with @ aren’t allowed as raw objects. See the @object tag for encoding rules on objects with `@`names.

@object

string

Object. Explicitly tagged objects are allowed to have property names starting with @. If an FQL object value includes properties starting with @, it is emitted on the wire in an @object tag.

@mod

string

Module, such as Math, Time, and Collection.

@date

string

Date value.
Example: 1970-01-01

@time

string

Time value.
Example: 1970-01-01T00:00:00+0000

@doc

id (string)
name (string)
ts
coll
< * >

Document. This document existed when the query executed and could be read successfully. One and only one of the id or name fields is present, depending on if the reference points to a named value or not. For example, roles have a name, so they have the name field and no id field.

@ref

id (string)
name (string)
coll
exists (Boolean, nullable)
cause (string, nullable)

Unresolved Document reference. The document may not exist. One and only one of the id or name fields is present, depending on if the reference points to a named value or not. For example, roles have a name, so they have the name field and no id field. When there is an exists field, it can be used to decide if the ref points to a document that can be read. If this field is set to false, a corresponding cause field indicates the reason that the document can’t be read. The current set of possible reasons are:

  • not found

  • permission denied

If the exists field isn’t present, the document might or might not exist.

@set

data ( [] )

after (string)

Set page. The after field is a string, which is a cursor that can be used to fetch the next page by passing it to Set.paginate().

@bytes

string

Base64-encoded string representing a byte array.
Name Type Description

x-format

string

Defines the encoded format expected for the query arguments field and the data field of a successful response.

Available values : simple, tagged

x-last-txn-ts

integer

If set, acts as the minimum snapshot time the query executes. Clients populate this based on the highest txn_ts result value observed of any transaction the client has processed.

x-linearized

Boolean

If true, unconditionally run the query as strictly serialized. This affects read-only transactions because transactions that write are already strictly serialized. See Transactions.

x-max-contention-retries

integer

The maximum number of times the system retries a transaction because of contention failure before an error is returned.

x-query-tags

string

A string-encoded set of caller-defined tags, which identify the request. Provided back in the logging and the query response body. The format is a list of key:value pairs. For example:

- foo=bar - foo=bar,baz=blah

Each key and each value may only include the characters [a-zA-Z0-9_]. These are also valid tags.

- foo_bar=baz - foo3=1234,5=6

All these are invalid.

- foo bar=3 // no spaces - foo=bar, // no trailing commas - foo==bar // too many =

Each key must be less than or equal to 40 bytes. Each value must be less than or equal to 80 bytes. There can be only a maximum of 25 key:value pairs, and the full header can’t exceed 3000 bytes.

x-query-timeout-ms

integer

Query timeout in milliseconds.

x-typecheck

Boolean

Enable or disable type checking of the query before evaluation. Defaults to the value of typechecked on the database configuration.

Examples

[expand]

Request:

curl -X POST \
  'https://db.fauna.com/query/1' \
  -H 'Authorization: Bearer $FAUNA_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"query": "Category.all()"}'

Response:

{
  "data": {
    "data": [
      {
        "id": "<CATEGORY_DOCUMENT_ID>",
        "coll": "Category",
        "ts": "2099-07-31T13:04:37.440Z",
        "products": "hdW...",
        "name": "party",
        "description": "Party Supplies"
      },
      {
        "id": "<CATEGORY_DOCUMENT_ID>",
        "coll": "Category",
        "ts": "2099-07-31T13:04:37.440Z",
        "products": "hdW...",
        "name": "frozen",
        "description": "Frozen Foods"
      },
      {
        "id": "<CATEGORY_DOCUMENT_ID>",
        "coll": "Category",
        "ts": "2099-07-31T13:04:37.440Z",
        "products": "hdW...",
        "name": "produce",
        "description": "Fresh Produce"
      }
    ]
  },
  "static_type": "Set<Category>",
  "summary": "",
  "txn_ts": 1722431381145911,
  "stats": {
    "compute_ops": 1,
    "read_ops": 11,
    "write_ops": 0,
    "query_time_ms": 8,
    "contention_retries": 0,
    "storage_bytes_read": 625,
    "storage_bytes_write": 0,
    "rate_limits_hit": []
  },
  "schema_version": 1722431077220000
}

 

Response

Content-Type: application/json

Example:

{
  "data": {
    "data": [
      {
        "id": "<CATEGORY_DOCUMENT_ID>",
        "coll": "Category",
        "ts": "2099-07-31T13:04:37.440Z",
        "products": "hdW...",
        "name": "party",
        "description": "Party Supplies"
      },
      {
        "id": "<CATEGORY_DOCUMENT_ID>",
        "coll": "Category",
        "ts": "2099-07-31T13:04:37.440Z",
        "products": "hdW...",
        "name": "frozen",
        "description": "Frozen Foods"
      },
      {
        "id": "<CATEGORY_DOCUMENT_ID>",
        "coll": "Category",
        "ts": "2099-07-31T13:04:37.440Z",
        "products": "hdW...",
        "name": "produce",
        "description": "Fresh Produce"
      }
    ]
  },
  "static_type": "Set<Category>",
  "summary": "",
  "txn_ts": 1722431381145911,
  "stats": {
    "compute_ops": 1,
    "read_ops": 11,
    "write_ops": 0,
    "query_time_ms": 8,
    "contention_retries": 0,
    "storage_bytes_read": 625,
    "storage_bytes_write": 0,
    "rate_limits_hit": []
  },
  "schema_version": 1722431077220000
}

200

Schema: QuerySuccess

Field name Type Description

data

object

Query execution data result.

txn_ts

integer

The transaction commit time in micros since epoch. Used by drivers to populate the x-last-txn-ts request header to get a consistent prefix RYOW guarantee.

summary

string

A comprehensive, human-readable summary of any errors, warnings, and logs returned from the query.

query_tags

The value of the x-query-tags header, if provided.

stats

Query statistics. See Query statistics fields.

Query statistics fields:

Field name Type Description

compute_ops

integer

Amount of Transactional Compute Ops consumed by the query.

read_ops

integer

Amount of Transactional Read Ops consumed by the query.

write_ops

integer

Amount of Transactional Write Ops consumed by the query.

query_time_ms

integer

Query run time in milliseconds.

storage_bytes_read

integer

Amount of data read from storage, in bytes.

storage_bytes_write

integer

Amount of data written to storage, in bytes.

contention_retries

integer

Number of transaction retries because of write contention.

rate_limits_hit

integer

Operations that exceeded their set rate limit.
Example value    [expand]

Response x-format: simple:

{
    "data": {
        "data": [
            {
                "id": "370622154499162180",
                "coll": "testCollection00",
                "ts": "2099-07-18T20:21:19.873Z",
                "name": "Alice"
            }
        ]
    },
    "summary": "",
    "txn_ts": 1689711820505751,
    "stats": {
        ... elided ..
    },
    "schema_version": 0
}

 

Response x-format: tagged:

{
    "data": {
        "@set": {
            "data": [
                {
                    "@doc": {
                        "id": "370622154499162180",
                        "coll": {
                            "@mod": "testCollection00"
                        },
                        "ts": {
                            "@time": "2099-07-18T20:21:19.873Z"
                        },
                        "name": "Alice"
                    }
                }
            ]
        }
    },
    "summary": "",
    "txn_ts": 1689712058554023,
    "stats": {
        ... elided ..
    },
    "schema_version": 0
}

 

x-format: tagged with @doc, @ref, @set responses:

400

Failed operation, bad request.    [expand]
Schema: QueryFailure    [expand]

A failed query response. Integrations that want to only report a human-readable version of the failure can print the summary field.

Field name Type Description

txn_ts

Int

The transaction commit time in micros since epoch. Used by drivers to populate the x-last-txn-ts request header to get a consistent prefix RYOW guarantee.

summary

String

A comprehensive, human-readable summary of any errors, warnings, and logs returned from the query.

query_tags

The value of the x-query-tags header, if provided.

stats

Query statistics. See the following query statistics fields.

Query statistics fields:

Field name Type Description

compute_ops

Int

Amount of Transactional Compute Ops consumed by the query.

read_ops

Int

Amount of Transactional Read Ops consumed by the query.

write_ops

Int

Amount of Transactional Write Ops consumed by the query.

query_time_ms

Int

Query run time in milliseconds.

storage_bytes_read

Int

Amount of data read from storage, in bytes.

storage_bytes_write

Int

Amount of data written to storage, in bytes.

contention_retries

Int

Number of transaction retries because of write contention.

rate_limits_hit

Array

Operations that exceeded their set rate limit. See Global limits.
Example values    [expand]

query check error

An error response that is the result of the query failing one or more validation tests.

{
  "error": {
    "code": "invalid_query",
    "message": "invalid query: the query failed 1 validation check"
  },
  "summary": "error: the function `len` doesn't exist on string 0: *query*:1\n  |\n1 | 'foo'.len()\n  |       ^^^\n  |"
}

 

runtime error

An error response that is the result of the query failing because of a runtime error. The code field varies based on the error cause.

{
  "error": {
    "code": "invalid_argument",
    "message": "invalid argument: expected value for `count` of type int, received string"
  },
  "summary": "error: expected value for `count` of type int, received string 0: *query*:1\n  |\n1 | User.all().take(\"bad\")\n  | ^^^^^^^^^^^^^^^^^^^^\n  |"
}

 

invalid request

The request body isn’t valid JSON or doesn’t conform to the API specification.

{
  "error": {
    "code": "invalid_request",
    "message": "invalid request: request body isn't valid JSON"
  }
}

 

abort call

The transaction called the abort() method. The error response includes custom abort data.

{
  "error": {
    "abort": {
      "@time": "2099-04-06T03:33:32.226Z"
    },
    "code": "abort",
    "message": "Query aborted."
  },
  "summary": "error: Query aborted. at *query*:1:6\n  |\n1 | abort(Time.now())\n  |      ^^^^^^^^^^^^\n  |"
}

value too large

The transaction exceeded one of the following global limits:

Array size

{
  "error": {
    "code": "value_too_large",
    "message": "Value too large: exceeded maximum number of elements (limit=16000)."
  },
  ...
}

String size

{
  "error": {
    "code": "value_too_large",
    "message": "Value too large: string size 27787264 exceeds limit 16777216."
  },
  ...
}

Array.sequence() range limit

{
  "error": {
    "code": "value_too_large",
    "message": "Value too large: range size 16001 exceeds limit 16000."
  },
  ...
}

401

Invalid or missing authentication token.    [expand]
Schema: QueryFailure    [expand]

A failed query response. Integrations that want to only report a human-readable version of the failure can print the summary field.

Field name Type Description

txn_ts

Int

The transaction commit time in micros since epoch. Used by drivers to populate the x-last-txn-ts request header to get a consistent prefix RYOW guarantee.

summary

String

A comprehensive, human-readable summary of any errors, warnings, and logs returned from the query.

query_tags

The value of the x-query-tags header, if provided.

stats

Query statistics. See the following query statistics fields.

Query statistics fields:

Field name Type Description

compute_ops

Int

Amount of Transactional Compute Ops consumed by the query.

read_ops

Int

Amount of Transactional Read Ops consumed by the query.

write_ops

Int

Amount of Transactional Write Ops consumed by the query.

query_time_ms

Int

Query run time in milliseconds.

storage_bytes_read

Int

Amount of data read from storage, in bytes.

storage_bytes_write

Int

Amount of data written to storage, in bytes.

contention_retries

Int

Number of transaction retries because of write contention.

rate_limits_hit

Array

Operations that exceeded their set rate limit. See Global limits.

    Headers: WWW-Authenticate, string

Example value    [expand] 
{
  "error": {
    "code": "unauthorized",
    "message": "invalid token: unable to authenticate request"
  }
}

409

Excessive contention while executing a query.   [expand]
Schema: QueryFailure    [expand]

A failed query response. Integrations that want to only report a human-readable version of the failure can print the summary field.

Field name Type Description

txn_ts

Int

The transaction commit time in micros since epoch. Used by drivers to populate the x-last-txn-ts request header to get a consistent prefix RYOW guarantee.

summary

String

A comprehensive, human-readable summary of any errors, warnings, and logs returned from the query.

query_tags

The value of the x-query-tags header, if provided.

stats

Query statistics. See the following query statistics fields.

Query statistics fields:

Field name Type Description

compute_ops

Int

Amount of Transactional Compute Ops consumed by the query.

read_ops

Int

Amount of Transactional Read Ops consumed by the query.

write_ops

Int

Amount of Transactional Write Ops consumed by the query.

query_time_ms

Int

Query run time in milliseconds.

storage_bytes_read

Int

Amount of data read from storage, in bytes.

storage_bytes_write

Int

Amount of data written to storage, in bytes.

contention_retries

Int

Number of transaction retries because of write contention.

rate_limits_hit

Array

Operations that exceeded their set rate limit. See Global limits.
Example value    [expand] 
{
  "error": {
    "code": "contended_transaction",
    "message": "Transaction aborted due to detection of concurrent modifications to <document>"
  }
}

429

The query exceeded some capacity limit.    [expand]

See Global limits.

Schema: QueryFailure    [expand]

A failed query response. Integrations that want to only report a human-readable version of the failure can print the summary field.

Field name Type Description

txn_ts

Int

The transaction commit time in micros since epoch. Used by drivers to populate the x-last-txn-ts request header to get a consistent prefix RYOW guarantee.

summary

String

A comprehensive, human-readable summary of any errors, warnings, and logs returned from the query.

query_tags

The value of the x-query-tags header, if provided.

stats

Query statistics. See the following query statistics fields.

Query statistics fields:

Field name Type Description

compute_ops

Int

Amount of Transactional Compute Ops consumed by the query.

read_ops

Int

Amount of Transactional Read Ops consumed by the query.

write_ops

Int

Amount of Transactional Write Ops consumed by the query.

query_time_ms

Int

Query run time in milliseconds.

storage_bytes_read

Int

Amount of data read from storage, in bytes.

storage_bytes_write

Int

Amount of data written to storage, in bytes.

contention_retries

Int

Number of transaction retries because of write contention.

rate_limits_hit

Array

Operations that exceeded their set rate limit. See Global limits.
Example value    [expand] 
{
  "error": {
    "code": "limit_exceeded",
    "message": "too many requests: the client sent too many requests"
  }
}

440

Exceeded the timeout defined in the request.   [expand]

Exceeded the timeout defined in the request, but the timeout is set lower than the expected query processing time. This response is distinguished from 503 by the fact that a 440 response is considered a successful response for the purpose of determining service availability.

Schema: QueryFailure    [expand]

A failed query response. Integrations that want to only report a human-readable version of the failure can print the summary field.

Field name Type Description

txn_ts

Int

The transaction commit time in micros since epoch. Used by drivers to populate the x-last-txn-ts request header to get a consistent prefix RYOW guarantee.

summary

String

A comprehensive, human-readable summary of any errors, warnings, and logs returned from the query.

query_tags

The value of the x-query-tags header, if provided.

stats

Query statistics. See the following query statistics fields.

Query statistics fields:

Field name Type Description

compute_ops

Int

Amount of Transactional Compute Ops consumed by the query.

read_ops

Int

Amount of Transactional Read Ops consumed by the query.

write_ops

Int

Amount of Transactional Write Ops consumed by the query.

query_time_ms

Int

Query run time in milliseconds.

storage_bytes_read

Int

Amount of data read from storage, in bytes.

storage_bytes_write

Int

Amount of data written to storage, in bytes.

contention_retries

Int

Number of transaction retries because of write contention.

rate_limits_hit

Array

Operations that exceeded their set rate limit. See Global limits.
Example value    [expand] 
{
  "error": {
    "code": "time_out",
    "message": "timeout: the client-specified processing time limit was exceeded."
  }
}

500

Unexpected error.   [expand]
Schema: QueryFailure    [expand]

A failed query response. Integrations that want to only report a human-readable version of the failure can print the summary field.

Field name Type Description

txn_ts

Int

The transaction commit time in micros since epoch. Used by drivers to populate the x-last-txn-ts request header to get a consistent prefix RYOW guarantee.

summary

String

A comprehensive, human-readable summary of any errors, warnings, and logs returned from the query.

query_tags

The value of the x-query-tags header, if provided.

stats

Query statistics. See the following query statistics fields.

Query statistics fields:

Field name Type Description

compute_ops

Int

Amount of Transactional Compute Ops consumed by the query.

read_ops

Int

Amount of Transactional Read Ops consumed by the query.

write_ops

Int

Amount of Transactional Write Ops consumed by the query.

query_time_ms

Int

Query run time in milliseconds.

storage_bytes_read

Int

Amount of data read from storage, in bytes.

storage_bytes_write

Int

Amount of data written to storage, in bytes.

contention_retries

Int

Number of transaction retries because of write contention.

rate_limits_hit

Array

Operations that exceeded their set rate limit. See Global limits.
Example value    [expand] 
{
  "error": {
    "code": "internal_error",
    "message": "internal error: an unexpected error occurred"
  }
}

502

Request couldn’t be routed.   [expand]
Schema: QueryFailure    [expand]

A failed query response. Integrations that want to only report a human-readable version of the failure can print the summary field.

Field name Type Description

txn_ts

Int

The transaction commit time in micros since epoch. Used by drivers to populate the x-last-txn-ts request header to get a consistent prefix RYOW guarantee.

summary

String

A comprehensive, human-readable summary of any errors, warnings, and logs returned from the query.

query_tags

The value of the x-query-tags header, if provided.

stats

Query statistics. See the following query statistics fields.

Query statistics fields:

Field name Type Description

compute_ops

Int

Amount of Transactional Compute Ops consumed by the query.

read_ops

Int

Amount of Transactional Read Ops consumed by the query.

write_ops

Int

Amount of Transactional Write Ops consumed by the query.

query_time_ms

Int

Query run time in milliseconds.

storage_bytes_read

Int

Amount of data read from storage, in bytes.

storage_bytes_write

Int

Amount of data written to storage, in bytes.

contention_retries

Int

Number of transaction retries because of write contention.

rate_limits_hit

Array

Operations that exceeded their set rate limit. See Global limits.
Example value    [expand] 
{
  "error": {
    "code": "bad_gateway",
    "message": "Bad Gateway"
  }
}

503

Unexpected timeout.    [expand]
Schema: QueryFailure    [expand]

A failed query response. Integrations that want to only report a human-readable version of the failure can print the summary field.

Field name Type Description

txn_ts

Int

The transaction commit time in micros since epoch. Used by drivers to populate the x-last-txn-ts request header to get a consistent prefix RYOW guarantee.

summary

String

A comprehensive, human-readable summary of any errors, warnings, and logs returned from the query.

query_tags

The value of the x-query-tags header, if provided.

stats

Query statistics. See the following query statistics fields.

Query statistics fields:

Field name Type Description

compute_ops

Int

Amount of Transactional Compute Ops consumed by the query.

read_ops

Int

Amount of Transactional Read Ops consumed by the query.

write_ops

Int

Amount of Transactional Write Ops consumed by the query.

query_time_ms

Int

Query run time in milliseconds.

storage_bytes_read

Int

Amount of data read from storage, in bytes.

storage_bytes_write

Int

Amount of data written to storage, in bytes.

contention_retries

Int

Number of transaction retries because of write contention.

rate_limits_hit

Array

Operations that exceeded their set rate limit. See Global limits.
Example value    [expand] 
{
  "error": {
    "code": "time_out",
    "message": "timeout: query timed out"
  }
}

504

Router timeout connecting to the backend.   [expand]
Schema: QueryFailure    [expand]

A failed query response. Integrations that want to only report a human-readable version of the failure can print the summary field.

Field name Type Description

txn_ts

Int

The transaction commit time in micros since epoch. Used by drivers to populate the x-last-txn-ts request header to get a consistent prefix RYOW guarantee.

summary

String

A comprehensive, human-readable summary of any errors, warnings, and logs returned from the query.

query_tags

The value of the x-query-tags header, if provided.

stats

Query statistics. See the following query statistics fields.

Query statistics fields:

Field name Type Description

compute_ops

Int

Amount of Transactional Compute Ops consumed by the query.

read_ops

Int

Amount of Transactional Read Ops consumed by the query.

write_ops

Int

Amount of Transactional Write Ops consumed by the query.

query_time_ms

Int

Query run time in milliseconds.

storage_bytes_read

Int

Amount of data read from storage, in bytes.

storage_bytes_write

Int

Amount of data written to storage, in bytes.

contention_retries

Int

Number of transaction retries because of write contention.

rate_limits_hit

Array

Operations that exceeded their set rate limit. See Global limits.
Example value    [expand] 
{
  "error": {
    "code": "gateway_timeout",
    "message": "Gateway Timeout"
  }
}

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!