Filter
Results
Backend API
There are several parameters you can use to effect the outcome of a query.
Query parameter reference for querying with Swell's Backend API.
Fields
where
objectAn object containing criteria to filter results by.
sort
stringA string expression used to sort results.
limit
intA number indicating the max number of results to return up to 1000.
page
intA number indicating which page of results to return.
search
stringA string to search and filter results by.
expand
stringA string or array of fields to expand in the result.
include
objectAn object with additional queries to include as fields in the result.
Use the where parameter to filter results by their values. Swell offers native support for most MongoDB Query Operators including comparison operators like $gt and $lt—logical operators like $and and $or—and many others. You can combine many fields in one query.
const swell = require('swell-node').init('store-id', 'secret-key');
await swell.get('/products', {
where: {
date_created: { $gte: '2018-01-01T00:00:00Z' },
stock_level: { $gt: 0 },
active: true,
},
});
Use the sort parameter to sort results. The format consists of <field> <direction>. Direction is recognized as a case-insensitive word like ascending and descending, or as abbreviated asc and desc.
You can combine multiple sort fields in a string or array, with the first taking precedence in order.
const swell = require('swell-node').init('store-id', 'secret-key');
await swell.get('/products', {
sort: 'name asc', // or desc
});
Use the limit parameter to determine how many records should be returned in a result, up to 1000. Defaults to 15. Optionally use in combination with page to perform pagination.
const swell = require('swell-node').init('store-id', 'secret-key');
await swell.get('/products', {
limit: 100,
});
Use the page parameter to determine which page of results to return, relative to the default or specified limit. Defaults to 1.
const swell = require('swell-node').init('store-id', 'secret-key');
await swell.get('/products', {
page: 2,
});
Use the search parameter to perform a text search across all text fields in a given collection. This is a basic implementation that uses a combination of regular expressions, meaning it will match exact words only. For example, a search for "blue shirts" will match records containing both the words "blue" and "shirts". Searching is not case-sensitive.
When building product search for a complex store, we recommend Algolia.
const swell = require('swell-node').init('store-id', 'secret-key');
await swell.get('/products', {
search: 'blue shirts',
});
Expanding allows you to include related records as defined by link or collection fields. For example, in the cart model, items are linked to a product with the product field which means they aren't automatically included in the result when retrieving a cart. Since the item product is nested in a list of objects, you would use dot-notation to specify the path to the expandable field.
When the expandable field refers to many records, you may want to specify a limit to include more than the default limit, which is 5. To do that for example, use the format variants:50 with the field name and limit separated by :.
When retrieving a list of results, expand will be performed on all records in the result set.
const swell = require('swell-node').init('store-id', 'secret-key');
await swell.get('/carts/{id}', {
id: '5407e0929fe97f9d4c712a5e',
expand: [
'items.product',
'items.variant',
],
});
Response
{
"id": "5407e0929fe97f9d4c712a5e",
"items": [
{
"id": "5407e0929fe97f9d4c712a5f",
"product_id": "5407e0929fe97f9d4c712a5g",
"product": {
"name": "Example product",
...
}
},
{...}
],
...
}Use the include parameter to include results in a query that may or may not be related to the records being retrieved. For example, when you know there's a need to retrieve two similar records at a time in order to reduce the number of API calls a page would need.
Use include.params to specify relative values to the records returned by the main query. The actual field values will be substituted by the API. Use include.data to specify literal values for filtering the included result.
const swell = require('swell-node').init('store-id', 'secret-key');
await swell.get('/orders/{id}', {
id: '5407e0929fe97f9d4c712a5f',
include: {
fulfilled_giftcards: {
url: '/giftcards',
params: {
order_id: 'id',
},
data: {
balance: { $gt: 0 },
},
},
},
});
Response
{
"id": "5407e0929fe97f9d4c712a5f",
"fulfilled_giftcards": [
{
"id": "5407e0929fe97f9d4c712a5g",
"balance": 25
},
{...}
],
...
}