Similar users

This page covers similar user queries for finding users similar to a given user. For query fundamentals, see Query Basics.

A similar user query returns users who are most similar to a given user. Common applications include finding users with similar preferences, building user segments, and enabling social features.

You can do user similarity in two ways:

1. Collaborative similarity, which finds users with similar interaction patterns - which users interact with the same items? The intuition is: "People who like this also like" - users who have similar interaction patterns.
2. Content similarity, which finds users with similar profile attributes (e.g., interests, demographics). The intuition is: "Users that have similar attributes to this user."

Collaborative similarity

Collaborative similarity finds users who interact with similar items, based on interaction patterns rather than profile attributes. This captures users who have similar tastes and preferences as evidenced by their behavior.

Intuition: "People who like this also like" - users who have similar interaction patterns.

Prerequisites

1. An engine with a trained collaborative embedding (e.g., ALS) configured for users
2. A user to find similar users for

Query example

To find similar users based on collaborative filtering (interaction patterns), use the similarity retrieve type with a precomputed user embedding:

ShapedQL

SELECT *
FROM similarity(embedding_ref='als_user_embedding',
               encoder='precomputed_user',
               input_user_id='$user_id',
               entity_type='users',
               limit=20)

Python SDK

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 SDK

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

Content similarity

Content similarity finds users who share similar profile attributes, such as interests, demographics, bio text, or other metadata. This is useful when you want to find users that are objectively similar in their characteristics.

Intuition: "Users that have similar attributes to this user."

Prerequisites

1. An engine with a content-based user embedding (e.g., text embedding from user profiles) configured
2. A user to find similar users for

Query example

To find similar users based on profile attributes (e.g., interests, bio text), use the similarity retrieve type with attribute pooling:

ShapedQL

SELECT *
FROM similarity(embedding_ref='text_user_embedding',
               encoder='user_attribute_pooling',
               input_user_id='$user_id',
               entity_type='users',
               limit=20)

Python SDK

from shaped import RankQueryBuilder, Similarity

# Find similar users based on profile attributes
query = (
    RankQueryBuilder()
    .from_entity('user')
    .retrieve(
        Similarity(
            embedding_ref='text_user_embedding',
            encoder={'type': 'user_attribute_pooling', 'input_user_id': '$user_id'},
            limit=20
        )
    )
    .build()
)

# Example usage with client
# response = client.rank(
#     query=query,
#     parameters={'user_id': 'user123'}
# )

TypeScript SDK

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

// Find similar users based on profile attributes
const query = new RankQueryBuilder()
  .from('user')
  .retrieve(step => 
    step.similarity({
      embeddingRef: 'text_user_embedding',
      encoder: { type: 'user_attribute_pooling', 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": "text_user_embedding",
        "query_encoder": {
          "type": "user_attribute_pooling",
          "input_user_id": "$parameters.user_id"
        },
        "limit": 20
      }
    ]
  },
  "parameters": {
    "user_id": "user123"
  }
}