Skip to main content
POST
/
knowledge
/
{knowledge_base_id}
/
query
Python
from opperai import Opper
import time

opper = Opper(http_bearer="YOUR_API_KEY")

# First, create a knowledge base
unique_name = f"company_policies_{int(time.time())}"
knowledge_base = opper.knowledge.create_base(
    name=unique_name, embedding_model="azure/text-embedding-3-large"
)

print(f"Created knowledge base: {knowledge_base.name}")
print(f"Knowledge base ID: {knowledge_base.id}")

# Add some HR policy documents to query against
hr_documents = [
    {
        "key": "vacation_policy_2024",
        "content": "Our company offers 25 days of paid vacation annually. Employees can carry over up to 5 unused days to the next year. Vacation requests must be submitted at least 2 weeks in advance through the HR portal.",
        "metadata": {
            "category": "hr_policies",
            "department": "hr",
            "last_updated": "2024-01-15",
        },
    },
    {
        "key": "sick_leave_policy",
        "content": "Employees are entitled to 12 days of paid sick leave per year. Sick leave does not carry over to the next year. Medical documentation may be required for absences longer than 3 consecutive days.",
        "metadata": {
            "category": "hr_policies",
            "department": "hr",
            "last_updated": "2024-01-10",
        },
    },
    {
        "key": "remote_work_policy",
        "content": "Employees may work remotely up to 3 days per week with manager approval. Remote work requests should be submitted one week in advance. All remote work must maintain productivity standards.",
        "metadata": {
            "category": "hr_policies",
            "department": "hr",
            "last_updated": "2024-02-01",
        },
    },
]

for doc in hr_documents:
    opper.knowledge.add_data(
        index_id=knowledge_base.id,
        content=doc["content"],
        key=doc["key"],
        metadata=doc["metadata"],
    )

print("Added HR policy documents to knowledge base")

# Query the knowledge base for relevant documents
results = opper.knowledge.query(
    index_id=knowledge_base.id,
    query="What are the company's vacation policies?",
    top_k=5,
    prefilter_limit=20,
    filters=[
        {"field": "category", "operation": "=", "value": "hr_policies"},
        {"field": "department", "operation": "in", "value": ["hr", "legal"]},
    ],
    rerank=True,
)

print(f"Found {len(results)} relevant documents:")
for result in results:
    print(f"Document: {result.key}")
    print(f"Score: {result.score:.3f}")
    print(f"Content: {result.content[:200]}...")
    print(f"Metadata: {result.metadata}")
    print("---")
[
  {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "key": "paris_123",
    "content": "The capital of France is Paris",
    "metadata": {
      "category": "product",
      "price": 100
    },
    "score": 0.95
  }
]

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
knowledge_base_id
string<uuid>
required

The id of the knowledge base to query

Body

application/json
​
query
string
required

Query string

Minimum length: 1
Example:

"What is the capital of France?"

​
prefilter_limit
integer
default:10

Number of documents to retrieve from the knowledge base before filtering

Required range: x > 0
Example:

10

​
top_k
integer
default:3

Number of documents to return

Required range: x > 0
Example:

3

​
filters
Filter · object[] | null

Per-field filters to apply to the query combined with AND

Example:
[
  {
    "field": "price",
    "operation": ">",
    "value": 100
  },
  {
    "field": "category",
    "operation": "in",
    "value": ["product", "service"]
  }
]
​
rerank
boolean
default:true

Whether to rerank the results

​
parent_span_id
string<uuid> | null

Parent span id

Response

Successful Response

​
id
string<uuid>
required

The id of the document

​
key
string
required

The key of the document

Example:

"paris_123"

​
content
string
required

The content of the document

Example:

"The capital of France is Paris"

​
metadata
object
required

The metadata of the document

Example:
{ "category": "product", "price": 100 }
​
score
number
required

The score of the document

Example:

0.95