Skip to main content

Queries

To retrieve data from a Shaped engine, you use a query. Queries let you retrieve results using pre-loaded or ad-hoc retrievers like similar_items or user_item_similarity.

Query types​

Queries can be either ad-hoc (defined at runtime) or saved (pre-defined in your engine configuration). Both types use retrievers to fetch and rank results from your engine.

Ad-hoc queries​

Ad-hoc queries are defined at runtime by the client. They allow you to experiment with different retrieval strategies without modifying your engine configuration.

Basic structure​

An ad-hoc query consists of:

  • type: The query type (e.g., rank_items)
  • retrieve: The retriever configuration
  • params: Runtime parameters passed to the query

Example: Similar items query​

Retrieve items similar to a given item using the item_similarity retriever:

fetch("https://api.shaped.ai/v1/datasets/movies/query", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({
    query: {
      type: "rank_items",
      retrieve: {
        name: "similar_items",
        embedding_ref: "als",
        type: "item_similarity",
        query_encoder: {
          input_item_id: "$param.item_id",
          type: "item_attribute_pooling"
        }
      }
    },
    params: {
      item_id: "db1234"
    }
  })
})

Saved queries​

Saved queries are declared in your engine configuration. They allow multiple clients (e.g., a mobile app and website) to execute the same queries against an engine, ensuring consistency across your application.

Defining saved queries​

Saved queries are defined in the queries section of your engine configuration:

version: v2
name: my_engine

data:
  item_dataset:
    name: movies

queries:
  - name: get_recommended_items
    type: rank_items
    retrieve:
      name: similar_items
      embedding_ref: als
      type: item_similarity
      query_encoder:
        input_item_id: $param.item_id
        type: item_attribute_pooling

Executing saved queries​

Execute a saved query by calling the query endpoint with the query name:

fetch("https://api.shaped.ai/v1/datasets/movies/queries/get_recommended_items", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({
    parameters: {
      item_id: "db1234"
    }
  })
})