Skip to main content

Search

The GraphQL API generated for your projects comes with a built-in search query. Here's a recipe for product searches that you can add to your frontend applications right now.

Add searchable data to your project

External/Remote data

Search queries access your project's indexed data without the need to fetch from remote services. To enable search for data from remote services like Shopify, BigCommerce or Stripe, you must import data into your project. There are two ways to do that:

  • The Import Data button
  • API Indexing

Import remote data

You can import data from a remote service by opening the service page in your project and selecting the Import Data button.

Index remote data

You can index data by selecting the API tab, expanding the Patterns & Services panel on the left, and selecting the three dots that appear when you hover over a service. Select "Configure Indexing" and follow the instructions in the modals that appear.

If you'd like to manually configure how your data is indexed, check out our API Indexing guide.

Create data

You can also search across data created in the admin UI. Read our guide for creating shapes to learn more.

Run a simple search query on your data

Once you have searchable data in your project, navigate to the API tab in the admin UI and run the following query in your API Explorer:

query {
search{
total
results {
_id
__typename
searchSummary
}
}
}

You should receive results similar to the following:

  "data": {
"search": {
"total": 20,
"results": [
{
"_id": "abcdefg-1234-5678-9000-ad0b2818e7c2",
"__typename": "Product",
"searchSummary": "product name here"
}
]
}
},

The above query returns the total count of searchable items in your project, and some basic data about each of them.

The search query has many arguments you can use to narrow the results down, including terms, which takes a string of search terms to filter the results by. If you're running the query in the API Explorer, you can always Ctrl+Select on the search query to see its arguments and fields in the Docs panel. You can also select the Docs panel icon above the API Explorer and search for search.

Using more specific search queries

If you import data using the Import Data button (as described above), you will have search queries tailored to your imported data added to your project. For example, if you import products from Shopify, the searchProductIndex query will be automatically added to your API.

You can then queries similar to the following:

query {
searchProductIndex{
total
results {
_id
__typename
searchSummary
}
}
}

The above query functions exactly the same as search, but only returns results for Product data.

Run a complex search query on your data

You can query more detailed data by using fragments. All searchable shapes in your project implement the TSSearchable interface, so fragments allow you to access fields specific to the data you want.

For example, the following query fetches all Stripe products in your project that contain the word shoe in their title, description or other data.

{
search(terms: "shoe") {
results {
__typename
... on Stripe_Product {
id
name
description
}
}
}
}

Using the where filter

You can run complex searches with the where filter argument. Using where in a search query, you can filter by types (Int, String, etc), date ranges, workflows, and more. You can also use logical operators like AND, NOT, and OR for more complex filtering.

Read our guide on advanced query filtering to learn more.

Below is a simple example of a query that searches for Stripe products that match the term "socks", filtering for active products.

{
search(terms:"socks", where:{active:{eq:true}}){
results {
__typename
... on Stripe_Product {
id
name
description
}
}
}
}

Check out our advanced query filtering guide for more examples.

Using search in your frontend applications

To implement search using the search query in your frontend application, define the query in your code and pass the filters you want to use as variables.

Below is an example of how you could define a query that fetches Stripe products with filters.

queries.ts
export const SearchStripeProducts = gql`
query SearchStripeProductsQuery($query: String!, $locale: String, $where: TSWhereInput) {
products: search(terms: $query, locale: $locale, where: $where) {
results {
__typename
... on Stripe_Product {
id
name
description
images
prices {
id
unitAmount: unit_amount
currency
recurring {
interval
intervalCount: interval_count
}
}
}
}
}
}
`;
Check out our NextJS eCommerce starter project to see search in action.

Our eCommerce starter project is deployed live on Vercel.

To see the code we use to implement our search, dive into the source code yourself.