Shaped

https://docs.shaped.ai/
Admin
Shaped is a platform for building and managing semantic search engines and recommendation systems...
Tokens:196,707
Snippets:1,655
Trust Score:9.4
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Required Packages

Source: https://docs.shaped.ai/docs/v2/tutorials/goodbooks

Install the necessary Python packages for the tutorial.

```bash
! pip install shaped  

! pip install pyyaml  
```

--------------------------------

### CLI Environment Setup Commands

Source: https://docs.shaped.ai/docs/v2/guides/errors

Commands to create and activate virtual environments for CLI installation.

```bash
python3.11 -m venv .venv
source ./.venv/bin/activate
pip install shaped
```

```bash
conda create --name myenv python=3.11
conda activate myenv
pip install shaped
```

--------------------------------

### CLI Installation and Activation Commands

Source: https://docs.shaped.ai/docs/v2/guides/errors

Commands to install the CLI and activate the environment.

```bash
pip install shaped
source ./path/to/env/bin/activate
```

--------------------------------

### Verify SDK Installation

Source: https://docs.shaped.ai/docs/v2/overview/install-sdk

Commands to confirm the package is correctly installed in the local environment.

```bash
npm list @shaped.ai/client
```

```bash
pip show shaped
```

--------------------------------

### Install and Verify Shaped SDK

Source: https://docs.shaped.ai/docs/v2/sdk/python_sdk

Commands to install the package via pip and verify the installation details.

```bash
pip install shaped
```

```bash
pip show shaped
```

--------------------------------

### CLI Installation Error Message

Source: https://docs.shaped.ai/docs/v2/guides/errors

Example of a build failure message when using an unsupported Python version.

```text
ERROR: Failed building wheel for pyarrow   
 
Failed to build pyarrow   
 
ERROR: Failed to build installable wheels for some pyproject.toml based projects (pyarrow)
```

--------------------------------

### Install Shaped SDK

Source: https://docs.shaped.ai/agents/AGENTS.md

Install the necessary client library for Python or TypeScript environments.

```bash
pip install shaped
```

```bash
npm install @shaped.ai/client
```

--------------------------------

### Clickhouse connector configuration example

Source: https://docs.shaped.ai/docs/v2/overview/upload_table

Example YAML configuration for connecting to a Clickhouse database.

```yaml
name: customer_click_events

description: Customer click events table for analytics and recommendations

schema_type: CLICKHOUSE

host: clickhouse.example.com

port: 9000

user: clickhouse_user

password: your_secure_password

database: analytics

table: customer_clicks

replication_key: created_at

columns:

  - user_id

  - item_id

  - click_timestamp

  - page_url

  - session_id

  - device_type

  - created_at

unique_keys:

  - user_id

  - item_id

  - click_timestamp
```

--------------------------------

### Install the TypeScript SDK

Source: https://docs.shaped.ai/docs/v2/sdk/typescript_sdk

Use npm or Yarn to add the client package to your project.

```bash
npm install @shaped.ai/client
```

```bash
yarn add @shaped.ai/client
```

--------------------------------

### ShapedQL Query Examples

Source: https://docs.shaped.ai/docs/v2/query_reference/shapedql

Examples demonstrating retrieval, scoring, and reranking using standard and engine-scoped syntax.

```sql
SELECT score(expression='m1') AS s, diversity(score=s, strength=0.3) AS r, *  

FROM retrieve(  

  similarity(embedding_ref='als', limit=50),  

  text_search(query='$query', limit=30)  

)  

WHERE category = 'electronics' ORDER BY r LIMIT 20
```

```sql
SELECT score(expression='m1') AS s, diversity(score=s, strength=0.3) AS r, *  

FROM engine.movieratings.retrieve(  

              similarity(embedding_ref='als', limit=50),  

              text_search(query='$query', limit=30)  

)  

WHERE category = 'electronics' ORDER BY r LIMIT 20
```

--------------------------------

### Install Data Dependencies

Source: https://docs.shaped.ai/docs/v2/tutorials/goodbooks

Install pandas for data manipulation.

```bash
! pip install pandas  
```

--------------------------------

### Instantiate Engine Configuration

Source: https://docs.shaped.ai/docs/v2/use_cases/image_embeddings

Initialize the engine configuration class to prepare for image search setup.

```python
from shaped.autogen.models.engine_config_v2 import EngineConfigV2  

from shaped.autogen.models.data_config import DataConfig  

  

image_search_engine = EngineConfigV2(  

    name="image_search",  

    data=DataConfig(),  

)  
```

```typescript
import { Engine } from '@shaped.ai/client';  

  

const imageSearchEngine = new Engine('image_search');  
```

--------------------------------

### Install Agent Context

Source: https://docs.shaped.ai/docs/v2/overview/agent_quickstart

Scripts to install agent context for standard-compliant agents or Claude Code.

```bash
curl -sSL https://docs.shaped.ai/agents/install.sh | sh
```

```bash
curl -sSL https://docs.shaped.ai/agents/claude.sh | sh
```

--------------------------------

### Initialize hybrid search engine

Source: https://docs.shaped.ai/docs/v2/use_cases/hybrid_search

Starts the indexing process for a configured engine.

```python
client.create_engine(engine_config=hybrid_search_engine)
```

```typescript
await client.createEngine(hybridSearchEngine);
```

--------------------------------

### Start encoding process

Source: https://docs.shaped.ai/docs/v2/use_cases/image_embeddings

Initialize the engine to begin encoding data for image search.

```python
client.create_engine(engine_config=image_search_engine)
```

```typescript
await client.createEngine(imageSearchEngine);
```

--------------------------------

### Create the engine

Source: https://docs.shaped.ai/docs/v2/sdk/python_sdk

Submit the configured engine to the client to start the encoding process.

```python
client.create_engine(engine_config=semantic_search_engine)  
```

--------------------------------

### Python SDK Filter Examples

Source: https://docs.shaped.ai/docs/v2/query_reference/shapedql

Examples of applying filters with static values and parameters using the Python SDK.

```python
from shaped import RankQueryBuilder, Filter  
  
  
# Simple filter expression  
query1 = (  
    RankQueryBuilder()  
    .from_entity('item')  
    .retrieve(  
        Filter(  
            where='category = "electronics" AND price < 100',  
            limit=200  
        )  
    )  
    .limit(20)  
    .build()  
)  
  
# Using parameters  
query2 = (  
    RankQueryBuilder()  
    .from_entity('item')  
    .retrieve(  
        Filter(  
            where='category = $category AND price < $max_price',  
            limit=100  
        )  
    )  
    .limit(10)  
    .build()  
)  
```

--------------------------------

### Personalized Hybrid Search Query Examples

Source: https://docs.shaped.ai/docs/v2/query_reference/search

Examples demonstrating how to retrieve and rank search results using different interfaces.

```ShapedQL
SELECT *  

FROM text_search(query='$query_text', mode='vector',   

                 text_embedding_ref='text_embedding', limit=50),  

     text_search(query='$query_text', mode='lexical', fuzziness=2, limit=50)  

ORDER BY score(expression='click_through_rate', input_user_id='$user_id', input_interactions_item_ids='$interaction_item_ids')  

LIMIT 20  
```

```python
from shaped import RankQueryBuilder, TextSearch  
  
# Basic lexical search  
query = (  
    RankQueryBuilder()  
    .from_entity('item')  
    .retrieve(  
        TextSearch(  
            query='$query_text',  
            mode='lexical',  
            fuzziness=2,  
            limit=20  
        )  
    )  
    .build()  
)  
  
# With parameters  
# response = client.rank(  
#     query=query,  
#     parameters={  
#         'query_text': 'Blue shirt'  
#     }  
# )  
```

```typescript
import { RankQueryBuilder } from '@shaped-ai/api';  
  
// Basic lexical search  
const query = new RankQueryBuilder()  
  .from('item')  
  .retrieve(step =>   
    step.textSearch({  
      query: '$query_text',  
      mode: { type: 'lexical', fuzziness: 2 },  
      limit: 20  
    })  
  )  
  .build();  
  
// With parameters  
// const response = await client.rank({  
//   query,  
//   parameters: {  
//     query_text: 'Blue shirt'  
//   }  
// });  
```

```json
{  
  "query": {  
    "type": "rank",  
    "from": "item",  
    "retrieve": [  
      {  
        "type": "text_search",  
        "input_text_query": "$parameters.query_text",  
        "mode": { "type": "vector", "text_embedding_ref": "text_embedding" },  
        "limit": 50  
      },  
      {  
        "type": "text_search",  
        "input_text_query": "$parameters.query_text",  
        "mode": { "type": "lexical", "fuzziness_edit_distance": 2 },  
        "limit": 50  
      }  
    ],  
    "score": {  
      "type": "score_ensemble",  
      "value_model": "click_through_rate",  
      "input_user_id": "$parameters.user_id",  
      "input_interactions_item_ids": "$parameters.interaction_item_ids"  
    },  
    "limit": 20  
  },  
  "parameters": {  
    "query_text": "Blue shirt",  
    "user_id": "user123",  
    "interaction_item_ids": ["item789", "item012"]  
  }  
}  
```

--------------------------------

### Start indexing process

Source: https://docs.shaped.ai/docs/v2/use_cases/text_search

Initializes the indexing process using the configured engine settings.

```python
client.create_engine(engine_config=text_search_engine)  
```

```typescript
await client.createEngine(textSearchEngine);  
```

--------------------------------

### Query with prebuilt filter

Source: https://docs.shaped.ai/docs/v2/query_reference/shapedql

Example of integrating a prebuilt filter into a retrieval query.

```sql
SELECT * FROM retrieve(similarity(embedding_ref='als', limit=100))  

WHERE price > 100 AND prebuilt('exclude_purchased', input_user_id='$user_id')  

LIMIT 20
```

--------------------------------

### Initialize search engine

Source: https://docs.shaped.ai/docs/v2/use_cases/semantic_search

Start the encoding process after configuring engine data and index.

```python
client.create_engine(engine_config=semantic_search_engine)
```

```typescript
await client.createEngine(semanticSearchEngine);
```

--------------------------------

### Collaborative similarity query examples

Source: https://docs.shaped.ai/docs/v2/query_reference/similar_users

Examples of performing collaborative similarity queries using various SDKs and query formats.

```ShapedQL
SELECT *  

FROM similarity(embedding_ref='als_user_embedding',  

               encoder='precomputed_user',  

               input_user_id='$user_id',  

               entity_type='users',  

               limit=20)
```

```Python
from shaped import RankQueryBuilder, Similarity  

  

# Find similar users based on collaborative filtering  

query = (  

    RankQueryBuilder()  

    .from_entity('user')  

    .retrieve(  

        Similarity(  

            embedding_ref='als_user_embedding',  

            encoder={'type': 'precomputed_user', 'input_user_id': '$user_id'},  

            limit=20  

        )  

    )  

    .build()  

)  

  

# Example usage with client  

# response = client.rank(  

#     query=query,  

#     parameters={'user_id': 'user123'}  

# )
```

```TypeScript
import { RankQueryBuilder } from '@shaped-ai/api';  

  

// Find similar users based on collaborative filtering  

const query = new RankQueryBuilder()  

  .from('user')  

  .retrieve(step =>   

    step.similarity({  

      embeddingRef: 'als_user_embedding',  

      encoder: { type: 'precomputed_user', inputUserId: '$user_id' },  

      limit: 20  

    })  

  )  

  .build();  

  

// Example usage with client  

# const response = await client.rank({  

#   query,  

#   parameters: { user_id: 'user123' }  

# });
```

```JSON
{
  "query": {
    "type": "rank",
    "from": "user",
    "retrieve": [
      {
        "type": "similarity",
        "embedding_ref": "als_user_embedding",
        "query_encoder": {
          "type": "precomputed_user",
          "input_user_id": "$parameters.user_id"
        },
        "limit": 20
      }
    ]
  },
  "parameters": {
    "user_id": "user123"
  }
}
```

--------------------------------

### Configure SingleStore dataset

Source: https://docs.shaped.ai/docs/v2/connectors/singlestore

Example configuration file for defining a SingleStore dataset connection.

```yaml
name: your_singlestore_dataset  

schema_type: MYSQL  

table: movies  

user: your_user  

password: pAssw0rd1!  

host: my-db.aws-virginia-6.svc.singlestore.com  

port: 3306  

database: movielens  

replication_key: updated_at  
```

--------------------------------

### Create the engine

Source: https://docs.shaped.ai/docs/v2/sdk/typescript_sdk

Start the encoding process by creating the engine via the client.

```typescript

await client.createEngine(semanticSearchEngine);  


```

--------------------------------

### Configure MSSQL table connector

Source: https://docs.shaped.ai/docs/v2/connectors/mssql

Example YAML configuration for a MSSQL dataset.

```yaml
name: your_mssql_dataset  

schema_type: MSSQL  

table: movies  

user: your_user  

password: pAssw0rd1!  

host: my-mssql-db.xxxxxxx.us-east-2.rds.amazonaws.com  

port: 3306  

database: movielens  

replication_key: updated_at  
```

--------------------------------

### Create an engine via CLI

Source: https://docs.shaped.ai/docs/v2/overview/train_engine

Upload the engine configuration file to initialize the engine in your account.

```bash
shaped create-engine --file engine.yaml
```

--------------------------------

### CLI Command Not Found Error

Source: https://docs.shaped.ai/docs/v2/guides/errors

Example of the error message displayed when the CLI is not installed or accessible.

```text
command not found: shaped
```

--------------------------------

### Create recommendation engine

Source: https://docs.shaped.ai/docs/v2/tutorials/steam_review

Command to initialize the engine using the configuration file.

```bash
shaped create-engine --file steam_review_engine_schema.yaml  
```

--------------------------------

### Create Tables from URI

Source: https://docs.shaped.ai/docs/v2/tutorials/amazon

Create tables for ratings and product metadata from JSONL files.

```bash
shaped create-table-from-uri --name amazon_beauty_ratings --type json --path ./All_Beauty.jsonl

shaped create-table-from-uri --name amazon_beauty_products --type json --path ./meta_All_Beauty.jsonl
```

--------------------------------

### Create Engine

Source: https://docs.shaped.ai/docs/v2/tutorials/amazon

Create the engine using the defined configuration file.

```bash
shaped create-engine --file amazon_beauty_product_recommendation.yaml
```

--------------------------------

### Create an engine from a config file

Source: https://docs.shaped.ai/docs/v2/sdk/cli

Initializes a new engine using a YAML configuration file.

```bash
shaped create-engine --config engine.yaml
```

--------------------------------

### GET /v2/engines/{engine_name}/queries/{query_name}

Source: https://docs.shaped.ai/docs/v2/query_reference/shapedql

Get details of a specific saved query.

```APIDOC
## GET /v2/engines/{engine_name}/queries/{query_name}

### Description
Retrieve the configuration details of a specific saved query.

### Method
GET

### Endpoint
/v2/engines/{engine_name}/queries/{query_name}

### Parameters
#### Path Parameters
- **engine_name** (string) - Required - The name of the engine.
- **query_name** (string) - Required - The name of the saved query.
```

--------------------------------

### Start Indexing and Training

Source: https://docs.shaped.ai/docs/v2/use_cases/personalized_search

Execute the engine creation to initiate data indexing and model training processes.

```python
client.create_engine(engine_config=personalized_search_engine)
```

```typescript
await client.createEngine(personalizedSearchEngine);
```

--------------------------------

### Create Table with Schema

Source: https://docs.shaped.ai/docs/v2/sdk/cli

Create a table using an explicit configuration file.

```bash
shaped create-table --config table.yaml
```

--------------------------------

### Install Shaped CLI via pip

Source: https://docs.shaped.ai/docs/v2/overview/installing-shaped-cli

Use this command to install the Shaped package from PyPi.

```bash
pip install shaped
```

--------------------------------

### Client Instantiation

Source: https://docs.shaped.ai/docs/v2/sdk/python_sdk

The Client class is the primary entry point for the SDK. It requires an API key for authentication.

```APIDOC
## Client(api_key: str)

### Description
Initializes the Shaped client for API interactions.

### Parameters
- **api_key** (str) - Required - The API key used for authentication.
```

--------------------------------

### Configure and Create Engine

Source: https://docs.shaped.ai/docs/v2/tutorials/lastfm

Define the engine configuration in YAML and initialize it using the CLI.

```yaml
data:  
  interaction_table:  
    type: query  
    query: |  
      SELECT user_id, artist_id AS item_id, 0 AS created_at, plays AS label  
      FROM lastfm_plays  
training:  
  models:  
    - name: als  
      policy_type: als
```

```bash
shaped create-engine --file lastfm_artist_recommendations.yaml
```

--------------------------------

### GET /tables/{table_name}

Source: https://docs.shaped.ai/docs/api

Get detailed information about a table, such as its columns structure and any errors or warnings.

```APIDOC
## GET /tables/{table_name}

### Description
Get detailed information about a table, such as its columns structure and any errors or warnings.

### Method
GET

### Endpoint
https://api.shaped.ai/v2/tables/{table_name}

### Parameters
#### Path Parameters
- **table_name** (string) - Required - Name of the table to retrieve.

#### Header Parameters
- **x-api-key** (string) - Required - API key for authentication (40 characters).

### Response
#### Success Response (200)
- **name** (string) - Unique identifier for the table.
- **uri** (string) - URI to access the table.
- **schema_type** (string) - Type of table schema (e.g., BIGQUERY).
- **status** (string) - Current deployment status (SCHEDULING, DEPLOYING, ACTIVE, INACTIVE, DESTROYING, ERROR).
- **created_at** (string) - Timestamp when the table was created.
- **schema** (object/null) - Table column names and their corresponding types.
- **kinesis_stream_arn** (string/null) - ARN of the Kinesis stream for real-time tables.
- **kinesis_iam_role_arn** (string/null) - ARN of the IAM role for Kinesis stream access.
- **kinesis_stream_name** (string/null) - Name of the Kinesis stream for real-time table integrations.
- **aws_region** (string/null) - AWS region of the Kinesis stream for real-time table integrations.
- **aws_access_key_id** (string/null) - AWS access key ID for configuring PostHog Kinesis delivery.
- **aws_secret_access_key** (string/null) - AWS secret access key for configuring PostHog Kinesis delivery.
- **description** (string/null) - Optional description of the table.
- **error_message** (string/null) - Error message if table is in error state.
- **warning_message** (string/null) - Warning message if there are any warnings.

#### Response Example
{
  "name": "string",
  "uri": "string",
  "schema_type": "string",
  "schema": { },
  "kinesis_stream_arn": "string",
  "kinesis_iam_role_arn": "string",
  "kinesis_stream_name": "string",
  "aws_region": "string",
  "aws_access_key_id": "string",
  "aws_secret_access_key": "string",
  "status": "SCHEDULING",
  "description": "string",
  "error_message": "string",
  "warning_message": "string",
  "created_at": "2019-08-24T14:15:22Z"
}
```

--------------------------------

### Array Parameters Example

Source: https://docs.shaped.ai/docs/v2/query_reference/shapedql

Example of how to pass an array of item IDs within the parameters object.

```json
{

  "parameters": {

    "item_ids": ["item1", "item2", "item3"]

  }

}
```

--------------------------------

### ShapedQL Filter Examples

Source: https://docs.shaped.ai/docs/v2/query_reference/shapedql

Examples of using filter expressions with static values and parameters in ShapedQL.

```sql
-- Simple filter expression  
SELECT * FROM retrieve(filter(where='category = "electronics" AND price < 100',   
                     limit=200))  
LIMIT 20  
  
-- Using a parameter  
SELECT * FROM retrieve(filter(where='category = $category AND price < $max_price',  
                     limit=100))  
LIMIT 10  
```

--------------------------------

### Cold Start Recommendations with Attribute Similarity

Source: https://docs.shaped.ai/docs/v2/query_reference/shapedql

Use attribute-based similarity for new users lacking interaction history.

```sql
SELECT score(expression='m1') AS s, diversity(score=s, strength=0.3) AS r, *  

FROM retrieve(similarity(embedding_ref='content_embedding',  

                         encoder='user_attribute_pooling',  

                         input_user_features='$user_features',  

                         limit=100))  

ORDER BY r LIMIT 20  
```

--------------------------------

### ShapedQL advanced retrieval examples

Source: https://docs.shaped.ai/docs/v2/query_reference/shapedql

Examples of using column_order with additional global filters and engine-specific paths.

```ShapedQL
SELECT * FROM column_order(columns='price DESC, rating ASC', limit=100)  

WHERE in_stock = true  

LIMIT 20  
```

```ShapedQL
SELECT * FROM engine.movieratings.retrieve(column_order(columns='price DESC, rating ASC', limit=100))  

WHERE in_stock = true  

LIMIT 20  
```

--------------------------------

### Create the engine via CLI

Source: https://docs.shaped.ai/docs/v2/tutorials/goodbooks

Initializes the engine using the previously generated YAML schema file.

```bash
"""  

Create a Shaped Engine using the .yaml schema file.  

"""  

  

! shaped create-engine --file $DIR_NAME/goodbooks_ratings_engine_schema.yaml
```

--------------------------------

### Lexical search examples

Source: https://docs.shaped.ai/docs/v2/query_reference/shapedql

Examples of performing lexical searches using standard and engine-specific retrieval paths.

```sql
-- Lexical search example  

SELECT name, price  

FROM retrieve(text_search(query='$query', mode='lexical', entity_type='items'))  
```

```sql
-- Lexical search example  

SELECT name, price  

FROM engine.movieratings.retrieve(text_search(query='$query', mode='lexical', entity_type='items'))  
```

--------------------------------

### TypeScript SDK Filter Examples

Source: https://docs.shaped.ai/docs/v2/query_reference/shapedql

Examples of applying filters with static values and parameters using the TypeScript SDK.

```typescript
import { RankQueryBuilder } from '@shaped-ai/api';  
  
// Simple filter expression  
const query1 = new RankQueryBuilder()  
  .from('item')  
  .retrieve(step =>   
    step.filter({  
      where: 'category = "electronics" AND price < 100',  
      limit: 200  
    })  
  )  
  .limit(20)  
  .build();  
  
// Using parameters  
const query2 = new RankQueryBuilder()  
  .from('item')  
  .retrieve(step =>   
    step.filter({  
      where: 'category = $category AND price < $max_price',  
      limit: 100  
    })  
  )  
  .limit(10)  
  .build();  
```

--------------------------------

### Basic Deployment Configuration

Source: https://docs.shaped.ai/docs/v2/engine_reference/engine-recipes

Minimal configuration using default settings with cold_tier storage and no autoscaling.

```yaml
deployment:  

  data_tier: cold_tier  
```

--------------------------------

### Python SDK advanced retrieval example

Source: https://docs.shaped.ai/docs/v2/query_reference/shapedql

Demonstrates complex column ordering with null handling and global filtering in Python.

```Python
from shaped import RankQueryBuilder, ColumnOrder  

  

query = (  

    RankQueryBuilder()  

    .from_entity('item')  

    .retrieve(  

        ColumnOrder(  

            columns=[  

                {'name': 'price', 'ascending': False, 'nulls_first': False},  

                {'name': 'rating', 'ascending': True}  

            ],  

            limit=100,  

            where='in_stock = true'  

        )  

    )  

    .limit(20)  

    .build()  

)  
```

--------------------------------

### Lexical Search Query Examples

Source: https://docs.shaped.ai/docs/v2/query_reference/search

Examples of performing a lexical search with fuzziness and limit parameters across different interfaces.

```ShapedQL
SELECT *  

FROM text_search(query='$query_text', mode='lexical', fuzziness=2, limit=20)  
```

```Python
from shaped import RankQueryBuilder, TextSearch  

  

# Basic lexical search  

query = (  

    RankQueryBuilder()  

    .from_entity('item')  

    .retrieve(  

        TextSearch(  

            query='$query_text',  

            mode='lexical',  

            fuzziness=2,  

            limit=20  

        )  

    )  

    .build()  

)  

  

# With parameters  

# response = client.rank(  

#     query=query,  

#     parameters={  

#         'query_text': 'Blue shirt'  

#     }  

# )  
```

```TypeScript
import { RankQueryBuilder } from '@shaped-ai/api';  

  

// Basic lexical search  

const query = new RankQueryBuilder()  

  .from('item')  

  .retrieve(step =>   

    step.textSearch({  

      query: '$query_text',  

      mode: { type: 'lexical', fuzziness: 2 },  

      limit: 20  

    })  

  )  

  .build();  

  

// With parameters  

// const response = await client.rank({  

//   query,  

//   parameters: {  

//     query_text: 'Blue shirt'  

//   }  

// });  
```

```JSON
{  

  "query": {  

    "type": "rank",  

    "from": "item",  

    "retrieve": [  

      {  

        "type": "text_search",  

        "input_text_query": "$parameters.query_text",  

        "mode": { "type": "lexical", "fuzziness_edit_distance": 2 },  

        "limit": 20  

      }  

    ]  

  },  

  "parameters": {  

    "query_text": "Blue shirt"  

  }  

}  
```

--------------------------------

### PostgreSQL Table Configuration Example

Source: https://docs.shaped.ai/docs/v2/connectors/postgresql

A YAML configuration file defining the connection parameters for a PostgreSQL dataset.

```yaml
name: your_postgres_dataset  

schema_type: POSTGRES  

table: movies  

user: your_user  

password: pAssw0rd1!  

host: my-postgres-db.xxxxxxx.us-east-2.rds.amazonaws.com  

port: 5432  

database: movielens  

replication_key: updated_at  
```

--------------------------------

### GET /views

Source: https://docs.shaped.ai/docs/api/v2

Lists all views for the authenticated tenant.

```APIDOC
## GET /views

### Description
List all views for the authenticated tenant.

### Method
GET

### Endpoint
https://api.shaped.ai/v2/views

### Parameters
#### Header Parameters
- **x-api-key** (string) - Required - API key for authentication (40 characters).

### Response
#### Success Response (200)
- **views** (Array of objects) - List of views and their metadata.

#### Response Example
{
  "views": [
    {
      "name": "string",
      "uri": "string",
      "created_at": "string",
      "type": "string",
      "status": "string",
      "source_table_names": ["string"],
      "description": "string"
    }
  ]
}
```

--------------------------------

### Using ShapedQL Parameters

Source: https://docs.shaped.ai/docs/v2/query_reference/shapedql

Examples demonstrating how to inject user IDs, search queries, and item lists into ShapedQL retrieval functions.

```sql
-- Using user_id parameter  

SELECT * FROM retrieve(similarity(embedding_ref='als',   

                       encoder='precomputed_user',  

                       input_user_id='$user_id'))  

LIMIT 10  

  

-- Using query parameter  

SELECT * FROM retrieve(text_search(query='$query', mode='lexical'))  

LIMIT 20  

  

-- Using item_ids parameter for reranking  

SELECT * FROM retrieve(ids($item_ids)) LIMIT 10
```

--------------------------------

### GET /tables/seeds

Source: https://docs.shaped.ai/docs/api

List all available seed tables.

```APIDOC
## GET /tables/seeds

### Description
List available seed tables.

### Method
GET

### Endpoint
https://api.shaped.ai/v2/tables/seeds

### Parameters
#### Header Parameters
- **x-api-key** (string) - Required - API key for authentication (40 characters).

### Response
#### Success Response (200)
- **tables** (Array) - Available seed tables.
  - **name** (string) - Table name to pass to seed endpoint.
  - **description** (string) - What this table contains.

#### Response Example
{
  "tables": [
    {
      "name": "string",
      "description": "string"
    }
  ]
}
```

--------------------------------

### ShapedQL column ordering examples

Source: https://docs.shaped.ai/docs/v2/query_reference/shapedql

Demonstrates ordering by single and multiple columns, as well as applying filter expressions.

```ShapedQL
-- Order by single column  

SELECT * FROM retrieve(column_order(columns='price DESC', limit=100))  
```

```ShapedQL
-- Order by multiple columns  

SELECT * FROM retrieve(column_order(columns='category ASC, price DESC', limit=100))  
```

```ShapedQL
-- With filter expression  

SELECT * FROM retrieve(column_order(  

    columns='rating DESC',   

    where='category = "electronics"',   

    limit=200  

))  
```

--------------------------------

### GET /v2/views

Source: https://docs.shaped.ai/docs/api

Retrieves a list of all views for the authenticated tenant.

```APIDOC
## GET https://api.shaped.ai/v2/views

### Description
List all views for the authenticated tenant.

### Method
GET

### Endpoint
https://api.shaped.ai/v2/views

### Parameters
#### Header Parameters
- **x-api-key** (string) - Required - API key for authentication (40 characters).

### Response
#### Success Response (200)
- **views** (Array of objects) - List of views and their metadata.

#### Response Example
{
  "views": [
    {
      "name": "string",
      "uri": "string",
      "created_at": "string",
      "type": "string",
      "status": "string",
      "source_table_names": ["string"],
      "description": "string"
    }
  ]
}
```

--------------------------------

### Query recommendations via CLI

Source: https://docs.shaped.ai/docs/v2/tutorials/amazon

Execute a similarity query using the CLI by providing the engine name, SQL query, and required parameters.

```bash
shaped query --engine-name amazon_beauty_product_recommendations \

  --query "SELECT * FROM similarity(embedding_ref='als', limit=50, encoder='precomputed_user', input_user_id='$user_id') LIMIT 5" \

  --parameters '{"user_id": "AHGHQ5SPYZ60Q"}'
```

```json
{

   "results": [

      {

         "id": "0002007770",

         "score": 0.98,

         "attributes": {

            "title": "Compact Hair Dryer",

            "price": 64.99

         }

      },

      {

         "id": "000100039X",

         "score": 0.92,

         "attributes": {

            "title": "Eye Balm",

            "price": 32.0

         }

      },

      {

         "id": "0002051850",

         "score": 0.73,

         "attributes": {

            "title": "Ear and Nose Hair Trimmer",

            "price": 12.99

         }

      },

      {

         "id": "0002219417",

         "score": 0.69,

         "attributes": {

            "title": "Pure Instinct Perfume",

            "price": 16.95

         }

      },

      {

         "id": "0000031887",

         "score": 0.68,

         "attributes": {

            "title": "Eye Shadow and Eye Liner Pen",

            "price": 15.99

         }

      }

   ]

}
```

--------------------------------

### GET /engines/seeds

Source: https://docs.shaped.ai/docs/api

Returns the list of available demo engines that can be seeded.

```APIDOC
## GET https://api.shaped.ai/v2/engines/seeds

### Description
Returns the list of available demo engines that can be seeded.

### Method
GET

### Endpoint
https://api.shaped.ai/v2/engines/seeds

### Parameters
#### Header Parameters
- **x-api-key** (string) - Required - API key for authentication (40 characters).

### Response
#### Success Response (200)
- **engines** (Array of objects) - Available seed engines.
  - **name** (string) - Engine name to pass to seed endpoint.
  - **description** (string) - What this engine does.

#### Response Example
{
  "engines": [
    {
      "name": "string",
      "description": "string"
    }
  ]
}
```

--------------------------------

### Download and Prepare Dataset

Source: https://docs.shaped.ai/docs/v2/tutorials/lastfm

Download the LastFM dataset and prepare the interaction file by adding headers and trimming to 100k samples.

```bash
curl http://mtg.upf.edu/static/datasets/last.fm/lastfm-dataset-360K.tar.gz -o lastfm-dataset-360K.tar.gz
tar -xzf lastfm-dataset-360K.tar.gz
```

```bash
(echo "user_id\tartist_id\tartist_name\tplays"; head -n 100000 lastfm-dataset-360K/usersha1-artmbid-artname-plays.tsv) > lastfm-dataset-360K/user-artist-plays-100k.tsv
```

```bash
wc -l lastfm-dataset-360K/usersha1-artmbid-artname-plays.tsv
```

--------------------------------

### Query with truncation

Source: https://docs.shaped.ai/docs/v2/query_reference/shapedql

Example of using truncate() within a retrieval query.

```sql
SELECT * FROM retrieve(similarity(embedding_ref='als', limit=1000))  

WHERE truncate(500)  

LIMIT 20
```

--------------------------------

### Manage Shell Completion

Source: https://docs.shaped.ai/docs/v2/sdk/cli

Commands for installing or previewing shell completion scripts.

```bash
shaped --install-completion
```

```bash
shaped --show-completion
```

--------------------------------

### GET /v2/engines/{engine_name}/queries

Source: https://docs.shaped.ai/docs/v2/query_reference/shapedql

List all saved queries for a specific engine.

```APIDOC
## GET /v2/engines/{engine_name}/queries

### Description
List all saved queries defined for the specified engine.

### Method
GET

### Endpoint
/v2/engines/{engine_name}/queries

### Parameters
#### Path Parameters
- **engine_name** (string) - Required - The name of the engine.
```

--------------------------------

### Instantiate Engine Configuration

Source: https://docs.shaped.ai/docs/v2/use_cases/rag_agents

Configure the semantic search engine by instantiating the engine configuration class.

```python
from shaped.autogen.models.engine_config_v2 import EngineConfigV2  

from shaped.autogen.models.data_config import DataConfig  

  

rag_engine = EngineConfigV2(  

    name="rag_search",  

    data=DataConfig(),  

)
```

```typescript
import { Engine } from '@shaped.ai/client';  

  

const ragEngine = new Engine('rag_search');
```

--------------------------------

### GET /views/{view_name}

Source: https://docs.shaped.ai/docs/api

Retrieves detailed information about a specific view by its name.

```APIDOC
## GET https://api.shaped.ai/v2/views/{view_name}

### Description
Get detailed information about a specific view.

### Method
GET

### Endpoint
https://api.shaped.ai/v2/views/{view_name}

### Parameters
#### Path Parameters
- **view_name** (string) - Required - Name of the view to retrieve.

#### Header Parameters
- **x-api-key** (string) - Required - API key for authentication (40 characters).

### Response
#### Success Response (200)
- **name** (string) - Unique identifier for the view.
- **uri** (string) - URI to access the view.
- **status** (string) - Current deployment status (ACTIVE, SCHEDULING, BACKFILLING, DESTROYING, INACTIVE, ERROR).
- **created_at** (string) - Timestamp when view was created.
- **source_table_names** (Array of strings) - List of source table names used by this view.
- **type** (string) - View type discriminator (e.g., "SQL").
- **schema** (object) - Schema definition mapping column names to value types.
- **description** (string) - Optional description of the view.
- **error_message** (string) - Error message if view is in error state.

#### Response Example
{
  "name": "string",
  "uri": "string",
  "status": "ACTIVE",
  "created_at": "2019-08-24T14:15:22Z",
  "schema": {},
  "source_table_names": ["string"],
  "description": "string",
  "error_message": "string",
  "type": "SQL"
}
```

--------------------------------

### Download sample dataset

Source: https://docs.shaped.ai/docs/v2/overview/upload_table

Download a sample JSONL file from S3 for testing purposes.

```bash
curl -L -O "https://shaped-onboarding-demo-datasets.s3.us-east-2.amazonaws.com/movielens/movielens_items.jsonl"
```

--------------------------------

### Personalized multi-faceted filtering

Source: https://docs.shaped.ai/docs/v2/query_reference/faceted_filtering

Example of combining multiple filters with personalization scoring.

```APIDOC
## Personalized multi-faceted filtering

### Description
Combine multiple filters with personalization to show users the most relevant items matching their filter criteria.

### Query Example (ShapedQL)
```sql
SELECT *
FROM column_order(columns='_derived_popular_rank ASC', limit=1000)
WHERE category = '$category'
  AND price >= $min_price
  AND price <= $max_price
ORDER BY score(expression='click_through_rate + 0.1 * user.age - 0.05 * item.price + 0.2 * item.rating', input_user_id='$user_id', input_interactions_item_ids='$interaction_item_ids')
LIMIT 20
```

### Query Example (JSON)
```json
{
  "query": {
    "type": "rank",
    "from": "item",
    "retrieve": [
      {
        "type": "column_order",
        "columns": [{ "name": "_derived_popular_rank", "ascending": true }],
        "limit": 1000,
        "where": "category = '$parameters.category' AND price >= $parameters.min_price AND price <= $parameters.max_price"
      }
    ],
    "score": {
      "value_model": "click_through_rate + 0.1 * user.age - 0.05 * item.price + 0.2 * item.rating",
      "input_user_id": "$parameters.user_id",
      "input_interactions_item_ids": "$parameters.interaction_item_ids"
    },
    "limit": 20
  },
  "parameters": {
    "category": "Electronics",
    "min_price": 50,
    "max_price": 200,
    "user_id": "user123"
  }
}
```
```
Tokens:
Raw