Make a query

Queries retrieve data from a Shaped engine. You can write ad-hoc queries to try different retrieval strategies at runtime, or run saved queries to standardize retrieval across your codebase. A query can do a single filter operation or run multiple retrievers in sequence.

Prerequisites

You need to set up the following before you can make a query:

1. Have a Shaped account with an API key - Get your API key
2. Have at least 1 table uploaded to Shaped - Upload a table
3. Have at least 1 engine trained - Train an engine

Make an ad-hoc query

Ad-hoc queries are defined at runtime by the client using ShapedQL (SQL).

ShapedQL

SELECT *
FROM similarity(embedding_ref='als',
               encoder='item_attribute_pooling',
               input_item_id=$item_id,
               limit=50)
LIMIT 20

JavaScript

fetch("https://api.shaped.ai/v2/engines/movies/query", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY"
  },
  body: JSON.stringify({
    query: "SELECT * FROM similarity(embedding_ref='als', limit=50, encoder='item_attribute_pooling', input_item_id=$item_id) LIMIT 20",
    parameters: {
      item_id: "db1234"
    }
  })
})

Python

import requests

response = requests.post(
    "https://api.shaped.ai/v2/engines/movies/query",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "YOUR_API_KEY"
    },
    json={
        "query": "SELECT * FROM similarity(embedding_ref='als', limit=50, encoder='item_attribute_pooling', input_item_id=$item_id) LIMIT 20",
        "parameters": {
            "item_id": "db1234"
        }
    }
)
print(response.json())

Execute a saved query

Saved queries are declared on the engine level. They allow multiple clients (eg a mobile app and website) to execute the same queries against an engine.

Save a query

In your engine config, set saved queries in the queries block. You can replace any runtime config like user ID or text query with parameters, with the syntax $params.parameter_name.

Run a query

At runtime, call the endpoint POST /v2/engines/{engine_name}/queries/{query_name}:

JavaScript

fetch("https://api.shaped.ai/v2/engines/movies/queries/get_recommended_items", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_API_KEY"
  },
  body: JSON.stringify({
    parameters: {
      user_id: "db1234"
    }
  })
})

Python

import requests

response = requests.post(
    "https://api.shaped.ai/v2/engines/movies/queries/get_recommended_items",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "YOUR_API_KEY"
    },
    json={
        "parameters": {
            "user_id": "db1234"
        }
    }
)
print(response.json())