Skip to main content

Filtering

When loading data, you will usually want to apply some kind of filtering or sorting to your query. Vulcan offers the following tools to help you get the data you need, whether you need to select a single document or a range of items.

Database vs GraphQL Fields​

Note that all sorting, filtering, etc. operations happen at the database level. So in all following examples, you can only filter and sort by database fields, not GraphQL-only fields.

Query Arguments​

The following arguments are available for both single-document and multi-documents queries.

Filter​

Vulcan queries and mutations take a filter argument to help you target one or more specific documents.

The filter argument can either accept a list of fields; or special _and, _not, and _or operators used to combine multiple filter selectors.

Each field can then in turn receive an operator such as _eq or _in depending on its type. Note that this API was heavily inspired by the Hasura API.

Here is an example MovieFilterInput input type:

input MovieFilterInput {
_and: [MovieFilterInput]
_not: MovieFilterInput
_or: [MovieFilterInput]
_id: String_Selector
createdAt: Date_Selector
userId: String_Selector
slug: String_Selector
title: String_Selector
}

And here is an example query using filter:

query MyMovie {
movie(input: { filter: { _id: { _eq: "123foo" } } }) {
result{
_id
title
year
}
}
}

You can use the filter argument to query for single documents, but if the filter matches more than one document only the first one will be returned.

With Mongo​

Available filters are visible in your GraphQL schema. You can search for any type ending in _Selector: String_Selector, Float_Selector...

Most parameters have transparent meaning: _eq, _lt, _lte, _gt, _gte, _in (for an array of values) etc.

The _like filter for strings will be translated as a case insensitive $regex call.

// Conversion table from Vulcan filters to Mongo selectors
_is_null: (value) => ({ $exists: !value }),
_is: (value) => ({ $elemMatch: { $eq: value } }),
_contains: (value) => ({ $elemMatch: { $eq: value } }),
_like: (value) => ({
$regex: value,
$options: "i",
}),

If you use ObjectId for document ids instead of strings, the GraphqlObjectId_Selector will be used. It supports basic operations: _eq, _in, _is_null, _neq.

With other databases​

The _filter function of each database connector translates Vulcan filters into a format that your database can understand. We only support Mongo out-of-the-box, but you can use it as an example to support more databases, SQL or No-SQL.

Custom Filters​

There are also cases where your query is too complex to be able to define it through the GraphQL API. For example, you could imagine a scenario where you have Movies and Reviews rating them on a five-star scale, and want to filter movies to only show those with a specific rating average.

In this case, you would define a server-side _withRating filter (starting with an underscore is a convention to differentiate the filter from field names), and then reference it in your query:

query MoviesWithRating {
movies(input: { filter: { _withRating: { average: 4 } } }) {
results{
_id
title
year
description
}
}
}

The filter function takes an argument object with the query input and context as properties; and should return an object with selector and options properties. Here's how you would define it:

const Movies = createGraphqlModelServer({
name: 'Movies',

graphql: {
typeName: 'Movie',
schema,
}

crud: {
customFilters: [
{
name: '_withRating',
arguments: 'average: Int',
filter: ({ input, context, filterArguments }) => {
const { average } = filterArguments;
const { Reviews } = context;
// get all movies that have an average review score of X stars
const xStarReviewsMoviesIds = getMoviesByScore(average);
return {
selector: { _id: {$in: xStarReviewsMoviesIds } },
options: {}
}
};
}
]
},
});
Custom Filters & Nested Fields​

Custom filters can be useful to work around the limitations of the filtering system. For example, unlike MongoDB the GraphQL filtering API does not let you filter based on nested document fields (e.g. addresses.country) since every filter needs to be defined in the GraphQL schema. But you can define a custom filter instead:

customFilters: [
{
name: '_withAddressCountry',
arguments: 'country: String',
filter: ({ input, context, filterArguments }) => {
const { country } = filterArguments;
return {
selector: { 'addresses.country': country },
options: {},
};
},
},
],

Sort​

query RecentMovies {
movies(input: { filter: { year: { gte: "2010" } }, sort: { year: "desc" } }) {
results{
_id
title
year
}
}
}

Custom Sorts​

Custom sorts are not yet implemented, but you can modify the options property returned by a custom filter to achieve the same effect.

In some cases you'll want to select data based on a field value, but without knowing exactly which field to search in. While you can build a complex query that lists every field needing to be searched, Vulcan also offers a shortcut in the form of the search argument:

query FightMovies {
movies(input: { search: "fight" ) {
results{
_id
title
year
description
}
}
}

On the server, Vulcan will search any field marked as searchable: true in its collection's schema for the string fight and will return the result.

Single-Document Queries Arguments​

The following arguments are only available for single-document queries.

ID​

Sometimes you already know the ID of the specific document you want to select. In those cases, you can use the id argument:

query myMovie {
movie(input: { id: "123foo" }) {
result{
_id
title
year
}
}
}

Multi Document Queries Arguments​

The following arguments are only available for multi-document queries.

Limit​

query RecentMovies {
movies(input: { filter: { year: { gte: 2010" } }, sort: { year: "desc" }, limit: 10 }) {
results{
_id
title
year
}
}
}

Offset​

query NextPageOfMovies {
movies(input: { offset: 10, limit: 10 }) {
results{
_id
title
year
}
}
}