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.
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
}
}
}
}
}
}
`;
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.