# Search

Searchable fulfillmenttools entities have a dedicated search endpoint located at `POST /api/{ENTITY-NAME}/search`. Each fulfillmenttools entity defines which of its fields are queryable. You can:

* Search string and number fields with the operators `eq`, `notEq`, `in`, and `notIn`. The search value for `eq` and `notEq` must be a string, while the value for `in` and `notIn` must be an array of strings.
* Search array-of-string fields with the `contains` operator.
* Search number and date fields with the operators `gt` (>), `gte` (>=), `lt` (<), and `lte` (<=).
* Search all `customAttributes`. However, to optimize performance, it's recommended to store search-relevant keys in a dedicated property (for example, `searchTerms`) and minimize nesting depth.

## Fields with default query limits

Some entities, particularly those representing historical data, include default filters in queries. These default search fields limit the amount of data returned, which improves performance and relevance.

For example, operational entities such as orders typically return only recently created records by default, as older data is often not relevant for current operations.

These default values can be overridden if needed. However, expanding filters requires caution, especially when querying large datasets, to avoid performance issues.

## Search function limitations

The search functionality has the following restrictions due to database constraints and performance considerations. These limitations ensure stability and efficiency when handling queries.

1. **No periods (`.`) in custom search field names:** Field names containing periods can cause conflicts with internal database structures and indexing mechanisms. To prevent issues, periods aren't allowed in custom search field names.
2. **No custom search fields starting with a dollar sign (`$`):** Field names beginning with a dollar sign conflict with database operators, which use this syntax for system commands. To avoid ambiguity, such field names aren't permitted.
3. **Cross-entity search via `referenced` filter is limited to top-level queries:** Cross-entity searches using the `referenced` filter can only be applied at the top level of a query. Nesting them within `AND` or `OR` conditions is not supported due to query optimization constraints.

## Search execution time limit

Each search request must complete within a 30-second time limit. If execution exceeds this limit, fulfillmenttools aborts the search and returns a `BadRequest` response. Long runtimes can result from a combination of query complexity and the volume of entities searched. When encountering timeouts, reduce the complexity (for example, simplify nested conditions, narrow filters, avoid overly broad `customAttribute` queries), narrow the size of the dataset (for example, by providing a time range or restricting the search to a specific facility), or contact the support team for guidance.

## Example API calls

### Searching for exact equal matches

Example: Search for stocks in a facility with `facilityRef` `d083f631-9f4c-463b-85d4-9414fb19239f`.

```http
POST https://{projectId}.api.fulfillmenttools.com/api/stocks/search
```

```json
{
    "query": {
        "facilityRef": {
            "eq": "d083f631-9f4c-463b-85d4-9414fb19239f"
        }
    }
}
```

### Searching with `gt`, `gte`, `lt`, and `lte` operators

Example: Search for storage locations with a `created` date before October 2, 2024.

```http
POST https://{projectId}.api.fulfillmenttools.com/api/storagelocations/search
```

```json
{
    "query": {
        "created": {
            "lt": "2024-10-02T14:43:21.257Z"
        }
    }
}
```

### Sorting search results

```http
POST https://{projectId}.api.fulfillmenttools.com/api/{ENTITY-NAME}/search
```

```json
{
    "sort": [
        {
            "<attribute_to_sort_by>": "ASC"
        }
    ],
    "query": {
      ...
    }
}
```

### Adding a search result total count

{% hint style="warning" %}
Requesting the total count can significantly increase the response time of the request.
{% endhint %}

```http
POST https://{projectId}.api.fulfillmenttools.com/api/{ENTITY-NAME}/search
```

```json
{
    "options": {
        "withTotal": true
    },
    "query": {
      ...
    }
}
```

{% hint style="info" %}
The `withTotal` option can't be used in combination with `after` for pagination. This restriction exists because the total count may change while paginating, which could lead to inconsistent results.
{% endhint %}

### Searching for several fields with `and` or `or`

Example: Search for stocks that have a `facilityRef` of `d083f631-9f4c-463b-85d4-9414fb19239f` and are also placed on either location `6779689d-4852-4fcf-b13b-78f5ce4954d8` or `3b8be595-6a00-40cf-be09-12195e44eb99`.

```http
POST https://{projectId}.api.fulfillmenttools.com/api/stocks/search
```

```json
{
    "query": {
        "and": [
            {
                "facilityRef": {
                    "eq": "d083f631-9f4c-463b-85d4-9414fb19239f"
                }
            }, {
                "locationRef": {
                    "in": [
                        "6779689d-4852-4fcf-b13b-78f5ce4954d8",
                        "3b8be595-6a00-40cf-be09-12195e44eb99"
                    ]
                }
            }
        ]
    }
}
```

### Searching for nested fields

Example: Search for `inboundProcesses` that reference a `purchaseOrder` with the `id` `678ujnuzb67vg8h8oji`.

```http
POST https://{projectId}.api.fulfillmenttools.com/api/inboundprocesses/search
```

```json
{
    "query": {
        "purchaseOrder": {
            "id": {
                "eq": "678ujnuzb67vg8h8oji"
            }
        }
    }
}
```

### Searching custom attributes

Example: Search for `customAttributes` of `suppliesOnlineCustomers` that's attributed to facilities.

```http
POST https://{projectId}.api.fulfillmenttools.com/api/facilities/search
```

```json
{
    "query": {
        "customAttributes": {
            "suppliesOnlineCustomers": {
                "eq": true
            }
        }
    }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fulfillmenttools.com/documentation/getting-started/search.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.