> For the complete documentation index, see [llms.txt](https://docs.chord.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chord.co/chord-oms/api-reference/searching.md). # Searching with Ransack OMS implements [Ransack](https://activerecord-hackery.github.io/ransack/) to allow searches on any GET index API endpoint without having to create additional endpoints specific for searching. Searches with Ransack are performed by including specific query parameters in the request. Multiple criteria can be passed as query parameters for more specific searches. The full list of search matchers can be found on the [Ransack Search Matchers page](https://activerecord-hackery.github.io/ransack/getting-started/search-matches/). Note that documentation for some endpoints includes Ransack details. However, Ransack is enabled for *many (but not all)* entities in ChordOMS, so these entities are searchable even if the documents for the corresponding endpoint do not specifically include Ransack details. If an entity is not searchable, please contact Chord to discuss the possibiliy of enabling search. ## Query format To filter by a field, append a `q` query parameter to the endpoint, combining the field name and a predicate: `?q[{field}_{predicate}]=value`. For example, `/api/orders/mine?q[state_eq]=complete` returns the current user's completed orders. ## Predicates | Predicate | Description | Notes | | ------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | \*\_eq | equal | | | \*\_not\_eq | not equal | | | \*\_matches | matches with LIKE | e.g. q\[email\_matches]=%@gmail.com | | \*\_does\_not\_match | does not match with LIKE | | | \*\_matches\_any | Matches any | | | \*\_matches\_all | Matches all | | | \*\_does\_not\_match\_any | Does not match any | | | \*\_does\_not\_match\_all | Does not match all | | | \*\_lt | less than | | | \*\_lteq | less than or equal | | | \*\_gt | greater than | | | \*\_gteq | greater than or equal | | | \*\_present | not null and not empty | Only compatible with string columns. Example: q\[name\_present]=1 (SQL: col is not null AND col != '') | | \*\_blank | is null or empty. | (SQL: col is null OR col = '') | | \*\_null | is null | | | \*\_not\_null | is not null | | | \*\_in | match any values in array | e.g. q\[name\_in]\[]=Alice\&q\[name\_in]\[]=Bob | | \*\_not\_in | match none of values in array | | | \*\_lt\_any | Less than any | SQL: col < value1 OR col < value2 | | \*\_lteq\_any | Less than or equal to any | | | \*\_gt\_any | Greater than any | | | \*\_gteq\_any | Greater than or equal to any | | | \*\_lt\_all | Less than all | SQL: col < value1 AND col < value2 | | \*\_lteq\_all | Less than or equal to all | | | \*\_gt\_all | Greater than all | | | \*\_gteq\_all | Greater than or equal to all | | | \*\_not\_eq\_all | none of values in a set | | | \*\_start | Starts with | SQL: col LIKE 'value%' | | \*\_not\_start | Does not start with | | | \*\_start\_any | Starts with any of | | | \*\_start\_all | Starts with all of | | | \*\_not\_start\_any | Does not start with any of | | | \*\_not\_start\_all | Does not start with all of | | | \*\_end | Ends with | SQL: col LIKE '%value' | | \*\_not\_end | Does not end with | | | \*\_end\_any | Ends with any of | | | \*\_end\_all | Ends with all of | | | \*\_not\_end\_any | | | | \*\_not\_end\_all | | | | \*\_cont | Contains value | uses LIKE | | \*\_cont\_any | Contains any of | | | \*\_cont\_all | Contains all of | | | \*\_not\_cont | Does not contain | | | \*\_not\_cont\_any | Does not contain any of | | | \*\_not\_cont\_all | Does not contain all of | | | \*\_i\_cont | Contains value with case insensitive | uses ILIKE | | \*\_i\_cont\_any | Contains any of values with case insensitive | | | \*\_i\_cont\_all | Contains all of values with case insensitive | | | \*\_not\_i\_cont | Does not contain with case insensitive | | | \*\_not\_i\_cont\_any | Does not contain any of values with case insensitive | | | \*\_not\_i\_cont\_all | Does not contain all of values with case insensitive | | | \*\_true | is true | | | \*\_false | is false | | See the [full list of predicates](https://github.com/activerecord-hackery/ransack/blob/main/lib/ransack/locale/en.yml) in the Ransack source. ## Examples To return all the products that have a variant SKU of **product-1-large-red** use the `q[sku_matches]=` parameter: ``` /api/variants?q[sku_matches]=product-1-large-red ``` To return all orders completed between August 2 and 4, 2024: ``` /api/orders?q[completed_at_gteq]=2024-08-02&q[completed_at_lteq]=2024-08-04 ``` All completed orders for the current user: ``` /api/orders/mine?q[state_eq]=complete ``` All subscriptions for a given user: ``` /api/subscriptions?q[user_id_in]={user_id} ``` All completed orders for a given user: ``` /api/orders?q[user_id_eq]={user_id}&q[state_eq]=complete ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.chord.co/chord-oms/api-reference/searching.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.