Insert a new pinning rule into the database. Pinning rules allow you to promote specific documents to specific positions in search results based on conditional matching of the search term.
Signature
function insertPin<T extends AnyOrama>(
orama: T,
rule: PinRule
): void
Parameters
The Orama database instance.
The pinning rule to insert.Unique identifier for the pinning rule. Used to update or delete the rule later.
Array of conditions that must all match (AND logic) for the rule to apply.Each condition contains:
anchoring: How to match the pattern ('is' | 'starts_with' | 'contains')pattern: The pattern to match against the search term
Actions to take when conditions match.Array of documents to promote, each containing:
doc_id: The document ID to promoteposition: Target position (0-based index)
Returns
This function returns nothing. Throws an error if a rule with the same ID already exists.
Examples
Basic Pin Rule
import { create, insert, insertPin, search } from '@orama/orama'
const db = await create({
schema: {
title: 'string',
description: 'string',
category: 'string'
}
})
await insert(db, { id: '1', title: 'Product A', category: 'electronics' })
await insert(db, { id: '2', title: 'Product B', category: 'electronics' })
await insert(db, { id: '3', title: 'Product C', category: 'electronics' })
// Pin Product B to position 0 when searching for "featured"
insertPin(db, {
id: 'featured-products',
conditions: [
{ anchoring: 'contains', pattern: 'featured' }
],
consequence: {
promote: [
{ doc_id: '2', position: 0 }
]
}
})
// Product B will now appear first
const results = await search(db, { term: 'featured products' })
console.log(results.hits[0].id) // '2'
Multiple Conditions (AND Logic)
// Only applies when term contains both "premium" AND "sale"
insertPin(db, {
id: 'premium-sale',
conditions: [
{ anchoring: 'contains', pattern: 'premium' },
{ anchoring: 'contains', pattern: 'sale' }
],
consequence: {
promote: [
{ doc_id: '5', position: 0 }
]
}
})
Exact Match Condition
// Only applies when search term exactly matches "best sellers"
insertPin(db, {
id: 'best-sellers',
conditions: [
{ anchoring: 'is', pattern: 'best sellers' }
],
consequence: {
promote: [
{ doc_id: '10', position: 0 },
{ doc_id: '15', position: 1 }
]
}
})
Starts With Condition
// Applies when search term starts with "new"
insertPin(db, {
id: 'new-arrivals',
conditions: [
{ anchoring: 'starts_with', pattern: 'new' }
],
consequence: {
promote: [
{ doc_id: '20', position: 0 }
]
}
})
// Matches: "new products", "new arrivals", "newest"
// Does not match: "brand new", "what's new"
// Pin multiple documents to specific positions
insertPin(db, {
id: 'holiday-promotion',
conditions: [
{ anchoring: 'contains', pattern: 'holiday' }
],
consequence: {
promote: [
{ doc_id: 'holiday-1', position: 0 },
{ doc_id: 'holiday-2', position: 1 },
{ doc_id: 'holiday-3', position: 2 }
]
}
})
Error Handling
try {
insertPin(db, {
id: 'my-rule',
conditions: [{ anchoring: 'contains', pattern: 'test' }],
consequence: { promote: [{ doc_id: '1', position: 0 }] }
})
// Attempting to insert again with same ID will throw
insertPin(db, {
id: 'my-rule', // Same ID!
conditions: [{ anchoring: 'contains', pattern: 'other' }],
consequence: { promote: [{ doc_id: '2', position: 0 }] }
})
} catch (error) {
console.error(error.message)
// "PINNING_RULE_ALREADY_EXISTS: A pinning rule with id 'my-rule' already exists."
}
Notes
- Rule IDs must be unique. Use
updatePin() to modify existing rules
- Conditions are case-insensitive and trimmed
- All conditions in a rule must match (AND logic)
- Documents are pinned at the specified positions, pushing other results down
- Pinned documents that don’t appear in search results are ignored
- Pinning rules apply to all search modes (full-text, vector, and hybrid)
- Pattern matching is performed on the normalized search term