Skip to content
excalibase
filtering
GraphQL APIstable

Filtering

Every list, connection and aggregate field takes a where argument with per-column filter inputs. The examples run against the public demo project; send them as the query of a POST to $BASE/$PROJECT_ID/graphql with Authorization: Bearer $TOKEN, as in Connect to your project.

Operators

OperatorExample
eq, neqlabel: { eq: "Chat room" }
gt, gte, lt, lteposition: { gte: 1 }
in, notInid: { in: [1, 2] }
isNull, isNotNullposition: { isNotNull: true }
containslabel: { contains: "Chat" }
startsWith, endsWithlabel: { startsWith: "Chat" }
likelabel: { like: "Chat%" }
ilikelabel: { ilike: "%chat%" }

contains, startsWith, endsWith and like are case-sensitive; use ilike to ignore case. JSON columns also take hasKey, hasKeys, hasAnyKeys, contains and containedBy (on MySQL they take no eq or neq); Postgres array columns take contains, containedBy, overlaps, arrayContains, arrayHasAny and arrayHasAll. Which operators a column accepts depends on its type and database.

AND, OR

Several conditions in one where are ANDed. Combine groups with and and or inside where:

{
  publicLivePollOptions(where: {
    position: { gte: 1 }
    label: { neq: "Recipe box" }
  }) {
    label
    position
  }
}
{
  publicLivePollOptions(where: {
    or: [
      { label: { eq: "Chat room" } }
      { label: { eq: "Guestbook" } }
    ]
  }) {
    label
  }
}

Text search

{
  publicLivePollOptions(where: { label: { ilike: "%chat%" } }) {
    label
  }
}

Relationships

A nested field is filtered by the caller's permissions on the table it reaches, and takes the same where, orderBy, limit and offset:

{
  publicLivePollPolls(limit: 1) {
    question
    publicLivePollOptions(where: { position: { lt: 2 } }, orderBy: { position: DESC }) {
      label
      position
    }
  }
}

Sorting and pagination

{
  publicLivePollOptions(orderBy: { position: DESC }, limit: 2, offset: 1) {
    position
    label
  }
}

limit is capped by the server and by the role's permission, so a list never returns more than the role may read in one request.

Cursor pagination

A ...Connection field returns Relay-style edges, cursors and pageInfo. Pass the last endCursor as after for the next page:

{
  publicLivePollOptionsConnection(first: 2) {
    edges {
      cursor
      node { id label }
    }
    pageInfo { hasNextPage endCursor }
  }
}

totalCount is available only where the role's permission sets allowAggregations.