Sorting 

The example-app GraphQL API can sort the records returned by the sortable fields for each model. If you pass the sort argument to a find call, you can pass the fields and directions to sort by.

await api.post.findMany({
  sort: {
    publishedAt: "Descending",
  },
});

1const [result, refresh] = useFindMany(api.post, {
2  sort: {
3    publishedAt: "Descending",
4  },
5});
6const { data, error, fetching } = result;

1query FindManyPosts($sort: [PostSort!]) {
2  posts(sort: $sort) {
3    edges {
4      node {
5        id
6        publishedAt
7      }
8    }
9  }
10}

{ "sort": { "publishedAt": "Descending" } }

await api.post.findMany({
  sort: {
    publishedAt: "Descending",
  },
});

1const [result, refresh] = useFindMany(api.post, {
2  sort: {
3    publishedAt: "Descending",
4  },
5});
6const { data, error, fetching } = result;

You can sort on findMany, findFirst, and maybeFindFirst read calls using the API Client in Gadget.

Sort order 

Records can be ordered in either Descending or Ascending order for each field they are sorted on. Descending order will return the highest values first, while Ascending order will return the lowest values first. If sorting by multiple fields, each field can have a different order.

Sorting by multiple fields 

Records can be sorted by multiple fields by passing multiple sort orders in an array to your API call, like [ { fieldA: "Descending" }, { fieldB: "Ascending" }]. The first field will be used to order all the records, and then the second field will be used to break ties where records have the same value as the first field. Subsequent sorts will be used to break ties in the second field, etc.

await api.post.findMany({
  sort: [{ category: "Ascending" }, { publishedAt: "Descending" }],
});

1const [result, refresh] = useFindMany(api.post, {
2  sort: [
3    { category: "Ascending" },
4    {  publishedAt: "Descending" }
5  ]
6});
7const { data, error, fetching } = result;

1query FindManyPosts($sort: [PostSort!]) {
2  posts(filter: $filter) {
3    edges {
4      node {
5        id
6        publishedAt
7      }
8    }
9  }
10}

{ "sort": [{ "category": "Ascending" }, { "publishedAt": "Descending" }] }

await api.post.findMany({
  sort: [{ category: "Ascending" }, { publishedAt: "Descending" }],
});

1const [result, refresh] = useFindMany(api.post, {
2  sort: [
3    { category: "Ascending" },
4    {  publishedAt: "Descending" }
5  ]
6});
7const { data, error, fetching } = result;

Available fields for sorting 

Records can be sorted by most fields of their model in either the Ascending or Descending direction. The following field types are sortable:

Alphanumeric sorting rules 

Gadget uses Postgres's alphanumeric string sorting rules under the hood, which sorts spaces first, then numbers, then upper case letters, then special symbols, then lower case letters, then nulls.

For example, the following list of strings sorts in this order when sorted Ascending:

Copy
1"  spaces"
2"10-4"
3"123"
4"Apple"
5"Cube"
6"___"
7"anjou pear"
8"banana"
9null

Sorting by vector distance 

vector fields support vector-specific sort types for returning records in order of distance to a given vector. This implements a nearest neighbor search by querying all your stored vectors to find those that are most similar to an input vector on demand.

To sort by vector distance to a given vector field, pass an object with a to: input field with the vector to sort by.

If we have a document model with an embedding field of type vector, we can sort by the cosine distance to a given vector like so:

1await api.document.findMany({
2  sort: {
3    embedding: {
4      cosineSimilarityTo: [1, 2, 3], // etc
5    },
6  },
7});

1const [result, refresh] = useFindMany(api.document, {
2  sort: {
3    embedding: {
4      cosineSimilarityTo: [1, 2, 3] // etc
5    }
6  }
7});
8const { data, error, fetching } = result;

1query FindManyDocuments($sort: [DocumentSort!]) {
2  posts(filter: $filter) {
3    edges {
4      node {
5        id
6        embedding
7      }
8    }
9  }
10}

{ "sort": { "embedding": { "cosineSimilarityTo": [1, 2, 3] } } }

1await api.document.findMany({
2  sort: {
3    embedding: {
4      cosineSimilarityTo: [1, 2, 3], // etc
5    },
6  },
7});

1const [result, refresh] = useFindMany(api.document, {
2  sort: {
3    embedding: {
4      cosineSimilarityTo: [1, 2, 3] // etc
5    }
6  }
7});
8const { data, error, fetching } = result;

Available vector distance operations 

Vectors can be sorted by cosine similarity and L2 (Euclidian) distance to a given vector. Gadget generally recommends using cosine similarity for sorting, as it is more robust to changes in vector magnitude.

• To sort by cosine similarity, pass a sort like { fieldName: { cosineSimilarity: { to: [1,2,3] }}}. Cosine similarity will order by the most similar vectors first, ie cosine similarity descending.

1await api.document.findMany({
2  sort: {
3    embedding: {
4      cosineSimilarityTo: [1, 2, 3],
5    },
6  },
7});

1await api.document.findMany({
2  sort: {
3    embedding: {
4      cosineSimilarityTo: [1, 2, 3],
5    },
6  },
7});

• To sort by L2 distance, pass a sort like { fieldName: { l2Distance: { to: [1,2,3] }}}. L2 distance will order by the closest vectors first, ie L2 distance ascending.

1await api.document.findMany({
2  sort: {
3    embedding: {
4      l2DistanceTo: [1, 2, 3],
5    },
6  },
7});

1await api.document.findMany({
2  sort: {
3    embedding: {
4      l2DistanceTo: [1, 2, 3],
5    },
6  },
7});

Sorting by least similar 

Vectors can be sorted for least similarity by using one of the vector distance sorts with the order: "Ascending" option. This will return the least similar vectors first.

1await api.document.findMany({
2  sort: {
3    embedding: {
4      cosineSimilarityTo: [1, 2, 3], // etc
5      order: "Ascending",
6    },
7  },
8});

1const [result, refresh] = useFindMany(api.document, {
2  sort: {
3    embedding: {
4      cosineSimilarityTo: [1, 2, 3], // etc
5      order: "Ascending"
6    }
7  }
8});
9const { data, error, fetching } = result;

1query FindManyDocuments($sort: [DocumentSort!]) {
2  posts(filter: $filter) {
3    edges {
4      node {
5        id
6        embedding
7      }
8    }
9  }
10}

{
  "sort": { "embedding": { "cosineSimilarityTo": [1, 2, 3], "order": "Ascending" } }
}

1await api.document.findMany({
2  sort: {
3    embedding: {
4      cosineSimilarityTo: [1, 2, 3], // etc
5      order: "Ascending",
6    },
7  },
8});

1const [result, refresh] = useFindMany(api.document, {
2  sort: {
3    embedding: {
4      cosineSimilarityTo: [1, 2, 3], // etc
5      order: "Ascending"
6    }
7  }
8});
9const { data, error, fetching } = result;

Unsortable fields 

Currently, Gadget does not support sorting records by fields of the following types:

• file
• encrypted string
• password
• has many
• has one
• has many through
• computed

Filtering 

The example-app GraphQL API can filter records when reading to only the records matching certain conditions. If you pass a filter argument to a read API call, only records that match the filter will be returned.

await api.post.findMany({
  filter: {
    isPublished: { equals: true },
  },
});

1const [result, refresh] = useFindMany(api.post, {
2  filter: {
3   isPublished: {
4    equals: true
5   }
6  },
7});
8const { data, error, fetching } = result;

1query FindManyPosts($filter: [PostFilter!]) {
2  posts(filter: $filter) {
3    edges {
4      node {
5        id
6        isPublished
7      }
8    }
9  }
10}

{ "filter": { "isPublished": { "equals": true } } }

await api.post.findMany({
  filter: {
    isPublished: { equals: true },
  },
});

1const [result, refresh] = useFindMany(api.post, {
2  filter: {
3   isPublished: {
4    equals: true
5   }
6  },
7});
8const { data, error, fetching } = result;

You can filter on findMany, findFirst, and maybeFindFirst read requests using the API Client in Gadget.

Available fields for filtering 

Records can be filtered by most fields of their model, and the type of each model field determines what kind of filters are available in the API. For each field, Gadget uses a specific type for filtering that field type:

Each model then has a filter-specific GraphQL type that details the types of filters available on the selected model. For example, if there is a Post model to capture blog post records, there will also be a generated PostFilter GraphQL type. This filter type can be viewed in the API Reference or API Playground.

Combining filters 

Records can also be filtered by multiple different fields. If you want to combine filters using boolean logic, nest them under the AND, OR, or NOT keys of a parent filter.

await api.post.findMany({
  filter: {
    OR: [{ isPublished: { equals: true } }, { wordCount: { greaterThan: 500 } }],
  },
});

1const [result, refresh] = useFindMany(api.post, {
2  filter: {
3    OR: [
4      {
5        isPublished: { equals: true }
6      },
7      {
8        wordCount: { greaterThan: 500 }
9      }
10    ]
11  },
12});
13const { data, error, fetching } = result;

1query FindManyPosts($filter: [PostFilter!]) {
2  posts(filter: $filter) {
3    edges {
4      node {
5        id
6        isPublished
7      }
8    }
9  }
10}

1{
2  "filter": {
3    "OR": [
4      { "isPublished": { "equals": true } },
5      { "wordCount": { "greaterThan": 500 } }
6    ]
7  }
8}

await api.post.findMany({
  filter: {
    OR: [{ isPublished: { equals: true } }, { wordCount: { greaterThan: 500 } }],
  },
});

1const [result, refresh] = useFindMany(api.post, {
2  filter: {
3    OR: [
4      {
5        isPublished: { equals: true }
6      },
7      {
8        wordCount: { greaterThan: 500 }
9      }
10    ]
11  },
12});
13const { data, error, fetching } = result;

Filters can be nested deeply by passing multiple levels of boolean condition filters.

For example, we can fetch orders from a Shopify Order model where the total is between $100 and $200, and the order is either paid or refunded:

1api.shopifyOrder.findMany({
2  filter: {
3    AND: [
4      {
5        AND: [
6          { totalPrice: { greaterThan: 100 } },
7          { totalPrice: { lessThan: 200 } },
8        ],
9      },
10      {
11        OR: [
12          { financialStatus: { equals: "paid" } },
13          { financialStatus: { equals: "refunded" } },
14        ],
15      },
16    ],
17  },
18});

1const [{ data, error, fetching }, refresh] = useFindMany(api.shopifyOrder, {
2  filter: {
3    AND: [
4      { AND: [{ totalPrice: { greaterThan: 100 } }, { totalPrice: { lessThan: 200 } }]},
5      { OR: [{ financialStatus: { equals: "paid"} }, { financialStatus: { equals: "refunded" } }] }
6    ]
7  },
8});

1query FindManyShopifyOrders($filter: [ShopifyOrderFilter!]) {
2  shopifyOrders(filter: $filter) {
3    edges {
4      node {
5        id
6        totalPrice
7        financialStatus
8      }
9    }
10  }
11}

1{
2  "filter": [
3    {
4      "AND": [
5        { "totalPrice": { "greaterThan": 100 } },
6        { "totalPrice": { "lessThan": 200 } }
7      ]
8    },
9    {
10      "OR": [
11        { "financialStatus": { "equals": "paid" } },
12        { "financialStatus": { "equals": "refunded" } }
13      ]
14    }
15  ]
16}

1api.shopifyOrder.findMany({
2  filter: {
3    AND: [
4      {
5        AND: [
6          { totalPrice: { greaterThan: 100 } },
7          { totalPrice: { lessThan: 200 } },
8        ],
9      },
10      {
11        OR: [
12          { financialStatus: { equals: "paid" } },
13          { financialStatus: { equals: "refunded" } },
14        ],
15      },
16    ],
17  },
18});

1const [{ data, error, fetching }, refresh] = useFindMany(api.shopifyOrder, {
2  filter: {
3    AND: [
4      { AND: [{ totalPrice: { greaterThan: 100 } }, { totalPrice: { lessThan: 200 } }]},
5      { OR: [{ financialStatus: { equals: "paid"} }, { financialStatus: { equals: "refunded" } }] }
6    ]
7  },
8});

Filter types 

There are many different filter types available in Gadget. Each filter type corresponds to one or more field types.

Filtering on string and string-like fields 

Fields using the string type or other string-like field types like rich text, email, url can be filtered using string filters. For example, you can filter down to records where a string is equal to a given string:

1await api.student.findMany({
2  filter: {
3    firstName: {
4      equals: "Taylor",
5    },
6  },
7});

1await api.student.findMany({
2  filter: {
3    firstName: {
4      equals: "Taylor",
5    },
6  },
7});

Or filter to records where the stored string starts with a given string prefix:

1await api.post.findMany({
2  filter: {
3    title: {
4      startsWith: "How to",
5    },
6  },
7});

1await api.post.findMany({
2  filter: {
3    title: {
4      startsWith: "How to",
5    },
6  },
7});

The full list of supported filters on string and string-like fields are are:

• equals
• notEquals
• isSet
• in
• notIn
• startsWith
• lessThan
• lessThanOrEqual
• greaterThan
• greaterThanOrEqual

equals string filtering 

The equals filter key is used to filter down to records where the string field is equal to a given string. equals does a case-sensitive match to check if the incoming string is exactly equal to the stored string, and will only return records where that is true.

1await api.widget.findMany({
2  filter: {
3    name: {
4      equals: "gizmo",
5    },
6  },
7});

1await api.widget.findMany({
2  filter: {
3    name: {
4      equals: "gizmo",
5    },
6  },
7});

notEquals string filtering 

The notEquals filter key is used to filter down to records where the string field is set to anything other than a given string. notEquals does a case-sensitive match to check if the incoming string is exactly equal to the stored string, and will only return records where that is false.

1await api.widget.findMany({
2  filter: {
3    name: {
4      notEquals: "gizmo",
5    },
6  },
7});

1await api.widget.findMany({
2  filter: {
3    name: {
4      notEquals: "gizmo",
5    },
6  },
7});

isSet string filtering 

The isSet filter key is used to filter down to records where the string field is set to anything other than null. isSet will only return records where the value is not null.

1await api.widget.findMany({
2  filter: {
3    name: {
4      isSet: true,
5    },
6  },
7});

1await api.widget.findMany({
2  filter: {
3    name: {
4      isSet: true,
5    },
6  },
7});

isSet can also be used to check for null by passing isSet: false.

1await api.widget.findMany({
2  filter: {
3    name: {
4      isSet: false,
5    },
6  },
7});

1await api.widget.findMany({
2  filter: {
3    name: {
4      isSet: false,
5    },
6  },
7});

in string filtering 

The in filter key is used to filter down to records where the string field is exactly equal to one of the provided strings. in does a case-sensitive exact comparison between each of the provided strings to the string stored in the database, and will return records where the string field is equal to any of the provided strings. The in filter will never return records where the stored string is null.

1await api.widget.findMany({
2  filter: {
3    name: {
4      in: ["gizmo", "gadget"],
5    },
6  },
7});

1await api.widget.findMany({
2  filter: {
3    name: {
4      in: ["gizmo", "gadget"],
5    },
6  },
7});

notIn string filtering 

The notIn filter key is used to filter down to records where the string field is not equal to any of the provided strings. notIn does a case-sensitive exact comparison between each of the provided strings to the string stored in the database, and will return records where the string field is not equal to any of the provided strings. notIn will also return records where the stored string is null.

1await api.widget.findMany({
2  filter: {
3    name: {
4      notIn: ["gizmo", "gadget"],
5    },
6  },
7});

1await api.widget.findMany({
2  filter: {
3    name: {
4      notIn: ["gizmo", "gadget"],
5    },
6  },
7});

startsWith string filtering 

The startsWith filter key is used to filter down to records where the string field starts with the given string. This filter is case-sensitive and will return records where the string field begins with the specified substring. startsWith will never return records where the string field is set to null.

1await api.widget.findMany({
2  filter: {
3    name: {
4      startsWith: "giz",
5    },
6  },
7});

1await api.widget.findMany({
2  filter: {
3    name: {
4      startsWith: "giz",
5    },
6  },
7});

lessThan and lessThanOrEqual string filtering 

The lessThan filter key is used to filter down to records where the string field is lexicographically less than a given string. Lexicographically less means that the string comes before the given string in dictionary order, based on the Unicode values of the characters. For example, "apple" is lexicographically less than "banana", and "abc" is lexicographically less than "abd".

1await api.widget.findMany({
2  filter: {
3    name: {
4      lessThan: "gizmo",
5    },
6  },
7});

1await api.widget.findMany({
2  filter: {
3    name: {
4      lessThan: "gizmo",
5    },
6  },
7});

Similarly, the lessThanOrEqual filter key is used to filter down to records where the string field is lexicographically less than or equal to a given string.

1await api.widget.findMany({
2  filter: {
3    name: {
4      lessThanOrEqual: "gizmo",
5    },
6  },
7});

1await api.widget.findMany({
2  filter: {
3    name: {
4      lessThanOrEqual: "gizmo",
5    },
6  },
7});

greaterThan and greaterThanOrEqual string filtering 

The greaterThan filter key is used to filter down to records where the string field is lexicographically greater than a given string. Lexicographically greater means that the string comes after the given string in dictionary order, based on the Unicode values of the characters. For example, "banana" is lexicographically greater than "apple", and "abd" is lexicographically greater than "abc".

1await api.widget.findMany({
2  filter: {
3    name: {
4      greaterThan: "gizmo",
5    },
6  },
7});

1await api.widget.findMany({
2  filter: {
3    name: {
4      greaterThan: "gizmo",
5    },
6  },
7});

Similarly, the greaterThanOrEqual filter key is used to filter down to records where the string field is lexicographically greater than or equal to a given string.

1await api.widget.findMany({
2  filter: {
3    name: {
4      greaterThanOrEqual: "gizmo",
5    },
6  },
7});

1await api.widget.findMany({
2  filter: {
3    name: {
4      greaterThanOrEqual: "gizmo",
5    },
6  },
7});

Case-insensitive filtering 

Currently, Gadget has no filters for strings that do a case-insensitive comparison between the stored value and provided value. You can work around this by storing a second copy of the string on your model, and lowercasing it upon storage and upon filtering:

1export const run: ActionRun = async ({ params, record }) => {
2  applyParams(record, params);
3  // store the lowercase version of the name as well for filtering later
4  record.lowercaseName = record.name?.toLowerCase();
5  await save(record);
6};

1export const run: ActionRun = async ({ params, record }) => {
2  applyParams(record, params);
3  // store the lowercase version of the name as well for filtering later
4  record.lowercaseName = record.name?.toLowerCase();
5  await save(record);
6};

Then, you can filter on the lowercase name:

1await api.widget.findMany({
2  filter: {
3    lowercaseName: {
4      startsWith: "Giz".toLowerCase(),
5    },
6  },
7});

1await api.widget.findMany({
2  filter: {
3    lowercaseName: {
4      startsWith: "Giz".toLowerCase(),
5    },
6  },
7});

If native case-insensitivity is an important feature for you, please reach out to us in our Discord!

Filtering on number fields 

The number field type supports filtering on numeric fields. Numbers can be filtered by null-ness, equality, and by range.

For example, we can filter a post model by the wordCount number field to get all posts over 500 words:

1await api.posts.findMany({
2  filter: {
3    wordCount: {
4      greaterThan: 500,
5    },
6  },
7});

1await api.posts.findMany({
2  filter: {
3    wordCount: {
4      greaterThan: 500,
5    },
6  },
7});

Under the hood, your API generates different filter types for <FieldTypeTags.Number/> fields marked as integers or floats. The FloatFilter type is used for fields that have a decimal value, and the IntFilter type is used for fields that have an integer value. The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

The full list of supported filters on number fields are:

• equals
• notEquals
• isSet
• in
• notIn
• lessThan
• lessThanOrEqual
• greaterThan
• greaterThanOrEqual

equals number filtering 

The equals filter key is used to filter down to records where the number field is equal to a given number. equals does an exact match to check if the incoming number is exactly equal to the stored number, and will only return records where that is true.

1await api.widget.findMany({
2  filter: {
3    quantity: {
4      equals: 10,
5    },
6  },
7});

1await api.widget.findMany({
2  filter: {
3    quantity: {
4      equals: 10,
5    },
6  },
7});

notEquals number filtering 

The notEquals filter key is used to filter down to records where the number field is set to anything other than a given number. notEquals does an exact match to check if the incoming number is exactly equal to the stored number, and will only return records where that is false.

1await api.widget.findMany({
2  filter: {
3    quantity: {
4      notEquals: 10,
5    },
6  },
7});

1await api.widget.findMany({
2  filter: {
3    quantity: {
4      notEquals: 10,
5    },
6  },
7});

isSet number filtering 

The isSet filter key is used to filter down to records where the number field is set to anything other than null. isSet will only return records where the value is not null.

1await api.widget.findMany({
2  filter: {
3    quantity: {
4      isSet: true,
5    },
6  },
7});

1await api.widget.findMany({
2  filter: {
3    quantity: {
4      isSet: true,
5    },
6  },
7});

isSet can also be used to check for null by passing isSet: false.

1await api.widget.findMany({
2  filter: {
3    quantity: {
4      isSet: false,
5    },
6  },
7});

1await api.widget.findMany({
2  filter: {
3    quantity: {
4      isSet: false,
5    },
6  },
7});

in number filtering 

The in filter key is used to filter down to records where the number field is exactly equal to one of the provided numbers. in does an exact comparison between each of the provided numbers to the number stored in the database, and will return records where the number field is equal to any of the provided numbers. The in filter will never return records where the stored number is null.

1await api.widget.findMany({
2  filter: {
3    quantity: {
4      in: [10, 20],
5    },
6  },
7});

1await api.widget.findMany({
2  filter: {
3    quantity: {
4      in: [10, 20],
5    },
6  },
7});

notIn number filtering 

The notIn filter key is used to filter down to records where the number field is not equal to any of the provided numbers. notIn does an exact comparison between each of the provided numbers to the number stored in the database, and will return records where the number field is not equal to any of the provided numbers. notIn will also return records where the stored number is null.

1await api.widget.findMany({
2  filter: {
3    quantity: {
4      notIn: [10, 20],
5    },
6  },
7});

1await api.widget.findMany({
2  filter: {
3    quantity: {
4      notIn: [10, 20],
5    },
6  },
7});

lessThan and lessThanOrEqual number filtering 

The lessThan number key is used to filter down to records where the number field is less than a given number.

1await api.widget.findMany({
2  filter: {
3    quantity: {
4      lessThan: 10,
5    },
6  },
7});

1await api.widget.findMany({
2  filter: {
3    quantity: {
4      lessThan: 10,
5    },
6  },
7});

Similarly, the lessThanOrEqual filter key is used to filter down to records where the number field is less than or equal to a given number.

1await api.widget.findMany({
2  filter: {
3    quantity: {
4      lessThanOrEqual: 10,
5    },
6  },
7});

1await api.widget.findMany({
2  filter: {
3    quantity: {
4      lessThanOrEqual: 10,
5    },
6  },
7});