Skip to main content

Queries

To retrieve data from a Shaped engine, you use a query.

Queries retrieve results using built-in retrievers like popularity, item-to-item similarity, or a custom scoring model in your engine.

Make a query​

Every query should be a POST request to the /v1/models/{model_name}/query endpoint.

The following query retreives similar items using an ALS embedding model.

fetch("https://api.shaped.ai/v1/datasets/movies/query", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY"
  },
  body: JSON.stringify({
    query: {
      type: "rank",
      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"
    }
  })
})

Write your own queries​

The /query endpoint accepts ad-hoc queries that you define at runtime. You can use it to test different retrieval strategies without modifying your engine configuration.

{
  "query": {
    "type": "rank",
    "retrieve": [
      {
        "type": "text_search",
        "mode": {
          "type": "lexical"
        },
        "input_text_query": "Blue shirt"
      }
    ],
    "from": "item"
  }
}

Vector search retriever​

Popular retriever - Get most popular items​

{
    "query": {
        "type": "rank",
        "retrieve": [
            {
                "type": "column_order",
                "columns": [
                    {
                        "name": "_derived_popular_rank",
                        "ascending" : "true"
                    }
                ]
            }
        ],
        "from": "item"
    },
    "return_metadata": "true"
}

Similarity retriever - Get similar items to recent interactions​

{
    "query": {
        "type": "rank",
        "retrieve": [
            {
                "type": "similarity",
                "query_encoder": {
                    "type":"interaction_round_robin",
                    "input_user_id": "429"
                },
                "embedding_ref" : "item_content_embedding"
            }
        ],
        "from": "item"
    },
    "return_metadata": "true"
}
{
  "query": {
      "type": "rank",
      "retrieve": [
          {
              "type": "column_order",
              "columns": [
                  {
                      "name": "_derived_popular_rank",
                      "ascending" : "true"
                  }
              ],
              "where" : "index_group_name = 'Baby/Children'"
          }
      ],
      "from": "item"
  },
  "return_metadata": "true"
}
{
    "query": {
        "type": "rank",
        "retrieve": [
            {
                "type": "column_order",
                "columns": [
                    {
                        "name": "_derived_popular_rank",
                        "ascending": "true"
                    }
                ],
                "limit" : 1000
            }
        ],
        "score": {
            "value_model" : "lightgbm",
            "input_user_id" : "12345"
        },
        "from": "item"
    },
    "return_metadata": "true"
}

Use a saved query​

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. Pass the query input parameters in the request body.

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"
    }
  })
})