Public Queries

Overview

When you create and configure a Query, you can use generated queryKey to search through your data. It is important to note, that everyone with a valid query key can execute public queries (there is no authentication required) - with some limitations that are described in Access and Security.

How to execute the simplest public query? Docs

POST /v1/query/{queryKey}

{
  "searchText": "television",
  "limit": 3
}

Example response:

{
  "searchText": "television",
  "total": 2025,
  "limit": 3,
  "items": [
    { "title": "television samsung a1" },
    { "title": "television samsung a2" },
    { "title": "television LG" }
  ]
}

The exact fields in response depend on your query configuration, but it will always include these fields:

searchText - original user search query;
total - total number of items that match the search query. The returned amount will never be higher than 10 000, even if number of matching results is higher than that;
items - a list of items that match the searchText query.

How to use a GET query? Docs

You can pass all of the configuration as a GET query parameters:

GET /v1/query/{queryKey}?searchText=tv

If you need to pass arrays, or nested parameters, you can use the following format:

GET /v1/query/{queryKey}?searchText=tv&filters[price][gt]=300

How to query for ALL documents?

Just issue a POST or GET query with an empty search text:

{
  "searchText": ""
}

You can still use all of the other query parameters.

Pagination

Although default pagination parameters can be defined in Query Configuration, you can override them with a public query request, by using offset and limit parameters:

{
  "searchText": "television",
  "offset": 5,
  "limit": 10
}

Offset and limit will be returned with query results:

{
  "searchText": "television",
  "total": 2025,
  "items": [],
  "offset": 5,
  "limit": 10
}

Limitations:

offset parameter should not exceed 1000000;
limit parameter should not exceed 1000.

Both values cannot be negative.

How to convert page number parameter into offset and limit?

If you prefer using page number and and page size as parameters, you can use this formula to obtain offset and limit:

limit = pageSize

offset = (pageNumber - 1) * pageSize

The example above assumes, that page numbering starts from 1.

Sorting

Public query request allows overriding sort parameter, defined in Query configuration:

{
  "searchText": "television",
  "limit": 5,
  "sort": [
    {
      "price": "asc"
    },
    {
      "in_stock": "desc"
    }
  ]
}

For full docs on sorting, check: Query Configuration - Sorting

Filters

With public query you can add optional filtering parameters. These filters are merged with ones defined on Query configuration. In public query you can only use filter keys that are defined in Query facets or filterableFields configuration.

{
  "searchText": "TV",
  "filters": {
    "tag": ["Samsung"]
  }
}

All filters that were sent with a request are also returned back with a response:

{
  "searchText": "television",
  "total": 119,
  "items": [],
  "filters": {
    "tag": ["Samsung"]
  }
}

For full docs on available filters, check: Query Configuration - Filters

Exclusion filters

Similarly, with public query, you can add optional exclusion filtering parameters. These exclusion filters are merged with ones defined on Query configuration. In public query you can only use exclusion filter keys that are defined in Query facets or filterableFields configuration.

{
  "searchText": "TV",
  "exclusionFilters": {
    "tag": ["Samsung"]
  }
}

Facet configuration cannot be overridden with a public query request.

For full docs on available facets and their response schemas, check: Query Configuration - Facets

Metadata

Public query response may optionally return metadata, which contains additional info about your Query, Project and Index, and is used by our client library, where it describes document keys for common properties that are unique for your project. For example:

{
  "searchText": "milk",
  "total": 119,
  "items": [],
  "metadata": {
    "imageKey": "imageUrl",
    "priceKey": "price",
    "titleKey": "productName",
    "imageRoot": "https://www.lupasearch.com/images/"
  }
}

How to configure metadata on your Index? Docs

Metadata can be configured by updating Project or Index.

PUT /v1/indices/{your-index-id}

{
  "metadata": {
    "imageKey": "imageUrl",
    "priceKey": "price",
    "titleKey": "productName",
    "imageRoot": "https://www.lupasearch.com/images/"
  }
}

As metadata is used by our client library, make sure you are not removing any required keys.

Metadata can also be configured on your Project, and is merged with Index metadata, when returned with a Public Query. If metadata keys match, Index settings have a higher priority.

Access and Security

With a valid queryKey, it is possible for anyone to execute Public Query requests. However some unintended access can be limited by using metadata on your Project settings.

How to configure CORS for your public queries? Docs

PUT /v1/organizations/{your-organization}/projects/{your-project}

{
  "metadata": {
    "allowedOrigins": ["https://lupasearch.com", "http://localhost:9000/"]
  }
}

These settings will set appropriate access-control-allow-origin response header on Public Query endpoint, if actual request origin matches one of configured ones.

If allowedOrigins are not set, the request origin is not limited.

Suggestions

If your query key points to a Suggestion Index, the only available Public Query parameters are searchText and limit:

{
  "searchText": "f",
  "limit": 3
}

Suggestion query response body will contain a list of autocomplete suggestions for a given phrase:

[
  {
    "suggestion": "for kids"
  },
  {
    "suggestion": "face"
  },
  {
    "suggestion": "face mask"
  }
]

The maximum value of limit can be 1000, however larger values can negatively impact a performance of your query.

User and session id tracking

Public query can optionally include and fields, which is used to display more relevant search results, including personalization. More on this can be found here.