Basics

Filtering

Filtering the retrieved data is done by specifying a filter argument. The filter argument is customized to each specific type based on the available fields. In case of the sample schema, here are the specifications for available filter arguments for querying Book:

# this is Book-specific
input FilterBook {
    # basic boolean operators that combine conditions
    and: [FilterBook!]
    or: [FilterBook!]
    not: FilterBook

    # fields available for filtering (properties in EdgeQL)
    title: FilterString
    synopsis: FilterString
    isbn: FilterString
    author: NestedFilterAuthor
}

# this is Author-specific
input NestedFilterAuthor {
    # instead of boolean operations, "exists" check is available
    # for links
    exists: Boolean

    # fields available for filtering (properties in EdgeQL)
    name: FilterString
}

# this is generic
input FilterString {
    # "exists" check is available for every property, too
    exists: Boolean

    # equality
    eq: String
    neq: String

    # lexicographical comparison
    gt: String
    gte: String
    lt: String
    lte: String

    # other useful operations
    like: String
    ilike: String
}

Here are some examples of using a filter:

{
    Book(
        filter: {
            title: {
                eq: "Spam"
            }
        }
    ) {
        title
        synopsis
    }
}

SELECT
    Book {
        title,
        synopsis
    }
FILTER
    Book.title = 'Spam';

{
    Book(
        filter: {
            author: {
                name: {
                    eq:
            "Lewis Carroll"
                }
            }
        }
    ) {
        title
        synopsis
    }
}

SELECT
    Book {
        title,
        synopsis
    }
FILTER
    Book.author.name =
        'Lewis Carroll';

It is legal to provide multiple input fields in the same input object. They are all implicitly combined using a logical conjunction. For example:

{
    Book(
        filter: {
            title: {
                gte: "m",
                lt: "o"
            }
        }
    ) {
        title
    }
}

SELECT
    Book {
        title,
    }
FILTER
    Book.title >= 'm'
    AND
    Book.title < 'o';

It is possible to search for books that don’t specify the author for some reason:

{
    Book(
        filter: {
            author: {
              exists: false
            }
        }
    ) {
        id
        title
    }
}

SELECT
    Book {
        id,
        title
    }
FILTER
    NOT EXISTS
        Book.author;

Ordering

Ordering the retrieved data is done by specifying an order argument. The order argument is customized to each specific type based on the available fields, much like the filter. In case of the sample schema, here are the specifications for the available filter arguments:

# this is Author-specific
input OrderAuthor {
    # fields available for ordering (properties in EdgeQL)
    name: Ordering
}

# this is Book-specific
input OrderBook {
    # fields available for ordering (properties in EdgeQL)
    title: Ordering
    synopsis: Ordering
    isbn: Ordering
}

# this is generic
input Ordering {
    dir: directionEnum
    nulls: nullsOrderingEnum
}

enum directionEnum {
    ASC
    DESC
}

enum nullsOrderingEnum {
    SMALLEST    # null < any other value
    BIGGEST     # null > any other value
}

If the value of nulls is not specified it is assumed to be SMALLEST.

{
    Author(
        order: {
            name: {
                dir: ASC,
                nulls: BIGGEST
            }
        }
    ) {
        name
    }
}

SELECT
    Author {
        name,
    }
ORDER BY
    Author.name ASC
        EMPTY LAST;

Paginating

Paginating the retrieved data is done by providing one or more of the following arguments: first, last, before, and after. The pagination works in a similar way to Relay Connections. In case of the sample schema, here are the specifications for the available filter arguments:

# a relevant Query definition snippet
type Query {
    Author(
        filter: FilterAuthor,
        order: OrderAuthor,

        after: String,
        before: String,
        first: Int,
        last: Int,
    ): [Author!]

    # ... other Query fields
}

The after and before strings are, in fact, string representations of numeric indices under the particular filter and ordering (starting at “0”). This makes the usage fairly intuitive even without having Relay Connection edges and cursors.

The objects corresponding to the indices specified by before or after are not included.

{
    Author(
        order: {
            name: {
                dir: ASC
            }
        },
        first: 10
    ) {
        name
    }
}

SELECT
    Author {
        name,
    }
ORDER BY
    Author.name ASC
LIMIT 10;

{
    Author(
        order: {
            name: {
                dir: ASC
            }
        },
        after: "19",
        first: 10
    ) {
        name
    }
}

SELECT
    Author {
        name,
    }
ORDER BY
    Author.name ASC
OFFSET 20 LIMIT 10;

{
    Author(
        order: {
            name: {
                dir: ASC
            }
        },
        after: "19",
        before: "30"
    ) {
        name
    }
}

SELECT
    Author {
        name,
    }
ORDER BY
    Author.name ASC
OFFSET 20 LIMIT 10;

Variables

It is possible to use variables within GraphQL queries. They are mapped to variables in EdgeQL.

query ($title: String!) {
    Book(
      filter: {
        title: {
          eq: $title
        }
      }
    ) {
        title
        synopsis
    }
}

SELECT
   Book {
       title,
       synopsis,
   }
FILTER
    .title = $title;