When to Use Which Query (v1)

Aito provides different query types for different use cases. This guide helps you choose the right one.

Quick Reference

You want to...	Use	Why	Example
Filter data	_search	Deterministic, exact matches	Find products under $5
Predict a category	_predict	Probabilistic classification	Predict product tags
Rank best options	_recommend	Optimizes for a goal	Recommend products to buy
Estimate a number	_estimate	K-NN regression	Predict prices
Find similar items	_similarity	Distance-based ranking	Find related products

Search vs Predict

Use Search when you need exact, deterministic results:

• Filtering by specific values
• Retrieving known records
• Boolean conditions (AND, OR)

Use Predict when you want probabilistic answers:

• "What category is this likely to be?"
• "What tag should this product have?"
• Classification based on patterns in data

Example: Finding vs Predicting Products

Search - Find products in a specific category:

{
  "from": "products",
  "where": {
    "category": "100"
  },
  "limit": 5
}

Try in Playground

Predict - Predict the most likely category for a new product:

{
  "from": "products",
  "where": {
    "name": "Organic Fair Trade Coffee 500g"
  },
  "predict": "category"
}

Try in Playground

Predict vs Recommend

Use Predict when you want to classify or complete a single field:

• "Which processor should handle this invoice?"
• "What tags describe this product?"
• Predicting unknown values based on known fields

Use Recommend when you want to rank options that optimize a goal:

• "Which product should I show this user to maximize purchase?"
• "Which search result is most likely to be clicked?"
• Ranking items by predicted outcome likelihood

Example: Classification vs Ranking

Predict - Classify which processor should handle an invoice:

{
  "from": "invoices",
  "where": {
    "ProductName": "Cloud Services (AWS)",
    "Description": "For IT Department"
  },
  "predict": "Processor"
}

Try in Playground

Recommend - Rank products by purchase likelihood for a user:

{
  "from": "impressions",
  "where": {
    "context.user": "0"
  },
  "recommend": "product",
  "goal": { "purchase": true }
}

Try in Playground

Predict vs Estimate

Use Predict for categorical values (classification):

• Discrete outcomes: categories, labels, tags
• Returns probability distribution over possible values

Use Estimate for numeric values (regression):

• Continuous values: prices, quantities, durations
• Returns a single numeric estimate with K-NN

Example: Category vs Price

Predict - Predict product category (categorical):

{
  "from": "products",
  "where": {
    "name": "Rye bread"
  },
  "predict": "category"
}

Try in Playground

Estimate - Estimate product price (numeric):

{
  "from": "price_history",
  "where": {
    "product_id": "2000818700008",
    "category": "100",
    "is_weekend": false
  },
  "estimate": "sale_price"
}

Try in Playground

Recommend vs Similarity

Use Recommend when you have behavioral data with outcomes:

• "Show products that maximize purchase likelihood"
• Requires a goal (the outcome to optimize)
• Uses conversion patterns from training data

Use Similarity when you want content-based matching:

• "Find products similar to this one"
• No goal needed - purely based on feature similarity
• Works without behavioral data

Example: Behavioral vs Content-Based

Recommend - Products likely to be purchased (behavioral):

{
  "from": "impressions",
  "where": {
    "context.user": "veronica"
  },
  "recommend": "product",
  "goal": { "purchase": true }
}

Try in Playground

Similarity - Products with similar attributes (content):

{
  "from": "products",
  "similarity": {
    "name": "Juhla Mokka coffee 500g sj",
    "category": "108"
  },
  "limit": 5
}

Try in Playground

Decision Tree

                    What do you need?
                          │
          ┌───────────────┼───────────────┐
          │               │               │
    Exact matches    ML prediction   Find similar
          │               │               │
       _search            │          _similarity
                          │
          ┌───────────────┼───────────────┐
          │               │               │
    Classify/Label   Rank options   Estimate number
          │               │               │
       _predict      _recommend      _estimate

Summary

Query	Input	Output	Use When
_search	Filter conditions	Matching rows	You know exactly what you're looking for
_predict	Context fields	Probability distribution	You need to classify or predict a category
_recommend	Context + goal	Ranked items	You want to optimize for an outcome
_estimate	Context fields	Numeric value	You need to predict a continuous number
_similarity	Reference object	Similar items	You want content-based matching
_relate	Proposition	Correlations	You want to discover patterns