Skip to main content
This guide shows how to connect Pinecone or another third-party vector database to Orq.ai for custom RAG. Upsert and search records using the Pinecone SDK, then pass the retrieved results into an Orq.ai Deployment for generation. This pattern gives full control over data ingestion, embedding logic, and retrieval while leveraging Orq.ai’s prompt management and observability features. Before beginning, ensure an Orq.ai account exists. If not, sign up first. A Google Colab file is available to copy and run immediately. Replace the API key to get started. After completing this tutorial, visit the Orq.ai documentation for more advanced topics.
Orq.ai also includes a fully hosted knowledge base powered by Pinecone. This is a great option to enable retrieval without managing infrastructure. This guide is for users who prefer to connect their own Pinecone project or another third-party vector database.

​
Why External Vector Databases Matter

Connecting an external vector database gives full control over data ingestion, embedding logic, and scaling. This can be especially useful when:
  • Working with sensitive or proprietary datasets that need to stay within a controlled infrastructure
  • Using custom embeddings not generated within Orq.ai’s built-in knowledge base
  • Integrating with other data pipelines where the vector database is a shared component
  • Building multi-source retrieval systems that combine local and remote sources

​
Step 1: Install dependencies

Install the Orq SDK along with the Pinecone client and supporting tools: 
pip install -qU \
    pinecone \
    pinecone-notebooks \
    orq-ai-sdk \
    requests

​
Get an API key

An API key is required to make calls to a Pinecone project. Use the widget below to generate a key. Users without a Pinecone account will be signed up for the free Starter plan automatically.
Python
import os

if not os.environ.get("PINECONE_API_KEY"):
    from pinecone_notebooks.colab import Authenticate
    Authenticate()
Bash
export ORQ_API_KEY=<YOUR_ORQ_API_KEY>

​
Step 2: Initialize the Orq.ai and Pinecone clients

The Orq.ai client communicates with the Orq.ai platform. Initialize it with an API key stored as an environment variable (ORQ_API_KEY) or passed directly. Initialize the Pinecone client using the generated Pinecone API key: 
import os
from orq_ai_sdk import Orq
from pinecone import Pinecone

# Initialize a Pinecone client with your API key
api_key = os.environ.get("PINECONE_API_KEY")
pc = Pinecone(api_key=api_key)

# Initialize Orq
client = Orq(
  api_key=os.environ["ORQ_API_KEY"],
)

​
Step 3: Create an index

In Pinecone, there are two types of indexes for storing vector data: Dense indexes store dense vectors for semantic search, and sparse indexes store sparse vectors for lexical/keyword search. For this quickstart, create a dense index integrated with an embedding model hosted by Pinecone. With integrated models, upsert and search with text; Pinecone generates vectors automatically.
To use external embedding models instead, see Bring your own vectors.
# Create a dense index with integrated embedding

index_name = "dense-index"

if not pc.has_index(name=index_name):
    pc.create_index_for_model(
        name=index_name,
        cloud="aws",
        region="us-east-1",
        embed={
            "model":"llama-text-embed-v2",
            "field_map":{"text": "chunk_text"}
        }
    )

​
Step 4: Upsert records

Prepare a sample dataset of factual statements from different domains like history, physics, technology, and music. Format the data as records with an ID, text, and category. These objects are expected to contain a chunk_text key because of the field_map specified when creating the index above. Other fields not mapped in the field mapping, like category, will become metadata on the upserted records. 
# Define your dataset
records = [
    { "_id": "rec1", "chunk_text": "The Eiffel Tower was completed in 1889 and stands in Paris, France.", "category": "history" },
    { "_id": "rec2", "chunk_text": "Photosynthesis allows plants to convert sunlight into energy.", "category": "science" },
    { "_id": "rec3", "chunk_text": "Albert Einstein developed the theory of relativity.", "category": "science" },
    { "_id": "rec4", "chunk_text": "The mitochondrion is often called the powerhouse of the cell.", "category": "biology" },
    { "_id": "rec5", "chunk_text": "Shakespeare wrote many famous plays, including Hamlet and Macbeth.", "category": "literature" },
    { "_id": "rec6", "chunk_text": "Water boils at 100°C under standard atmospheric pressure.", "category": "physics" },
    { "_id": "rec7", "chunk_text": "The Great Wall of China was built to protect against invasions.", "category": "history" },
    { "_id": "rec8", "chunk_text": "Honey never spoils due to its low moisture content and acidity.", "category": "food science" },
    { "_id": "rec9", "chunk_text": "The speed of light in a vacuum is approximately 299,792 km/s.", "category": "physics" },
    { "_id": "rec10", "chunk_text": "Newton's laws describe the motion of objects.", "category": "physics" },
    { "_id": "rec11", "chunk_text": "The human brain has approximately 86 billion neurons.", "category": "biology" },
    { "_id": "rec12", "chunk_text": "The Amazon Rainforest is one of the most biodiverse places on Earth.", "category": "geography" },
    { "_id": "rec13", "chunk_text": "Black holes have gravitational fields so strong that not even light can escape.", "category": "astronomy" },
    { "_id": "rec14", "chunk_text": "The periodic table organizes elements based on their atomic number.", "category": "chemistry" },
    { "_id": "rec15", "chunk_text": "Leonardo da Vinci painted the Mona Lisa.", "category": "art" },
    { "_id": "rec16", "chunk_text": "The internet revolutionized communication and information sharing.", "category": "technology" },
    { "_id": "rec17", "chunk_text": "The Pyramids of Giza are among the Seven Wonders of the Ancient World.", "category": "history" },
    { "_id": "rec18", "chunk_text": "Dogs have an incredible sense of smell, much stronger than humans.", "category": "biology" },
    { "_id": "rec19", "chunk_text": "The Pacific Ocean is the largest and deepest ocean on Earth.", "category": "geography" },
    { "_id": "rec20", "chunk_text": "Chess is a strategic game that originated in India.", "category": "games" },
    { "_id": "rec21", "chunk_text": "The Statue of Liberty was a gift from France to the United States.", "category": "history" },
    { "_id": "rec22", "chunk_text": "Coffee contains caffeine, a natural stimulant.", "category": "food science" },
    { "_id": "rec23", "chunk_text": "Thomas Edison invented the practical electric light bulb.", "category": "inventions" },
    { "_id": "rec24", "chunk_text": "The moon influences ocean tides due to gravitational pull.", "category": "astronomy" },
    { "_id": "rec25", "chunk_text": "DNA carries genetic information for all living organisms.", "category": "biology" },
    { "_id": "rec26", "chunk_text": "Rome was once the center of a vast empire.", "category": "history" },
    { "_id": "rec27", "chunk_text": "The Wright brothers pioneered human flight in 1903.", "category": "inventions" },
    { "_id": "rec28", "chunk_text": "Bananas are a good source of potassium.", "category": "nutrition" },
    { "_id": "rec29", "chunk_text": "The stock market fluctuates based on supply and demand.", "category": "economics" },
    { "_id": "rec30", "chunk_text": "A compass needle points toward the magnetic north pole.", "category": "navigation" },
    { "_id": "rec31", "chunk_text": "The universe is expanding, according to the Big Bang theory.", "category": "astronomy" },
    { "_id": "rec32", "chunk_text": "Elephants have excellent memory and strong social bonds.", "category": "biology" },
    { "_id": "rec33", "chunk_text": "The violin is a string instrument commonly used in orchestras.", "category": "music" },
    { "_id": "rec34", "chunk_text": "The heart pumps blood throughout the human body.", "category": "biology" },
    { "_id": "rec35", "chunk_text": "Ice cream melts when exposed to heat.", "category": "food science" },
    { "_id": "rec36", "chunk_text": "Solar panels convert sunlight into electricity.", "category": "technology" },
    { "_id": "rec37", "chunk_text": "The French Revolution began in 1789.", "category": "history" },
    { "_id": "rec38", "chunk_text": "The Taj Mahal is a mausoleum built by Emperor Shah Jahan.", "category": "history" },
    { "_id": "rec39", "chunk_text": "Rainbows are caused by light refracting through water droplets.", "category": "physics" },
    { "_id": "rec40", "chunk_text": "Mount Everest is the tallest mountain in the world.", "category": "geography" },
    { "_id": "rec41", "chunk_text": "Octopuses are highly intelligent marine creatures.", "category": "biology" },
    { "_id": "rec42", "chunk_text": "The speed of sound is around 343 meters per second in air.", "category": "physics" },
    { "_id": "rec43", "chunk_text": "Gravity keeps planets in orbit around the sun.", "category": "astronomy" },
    { "_id": "rec44", "chunk_text": "The Mediterranean diet is considered one of the healthiest in the world.", "category": "nutrition" },
    { "_id": "rec45", "chunk_text": "A haiku is a traditional Japanese poem with a 5-7-5 syllable structure.", "category": "literature" },
    { "_id": "rec46", "chunk_text": "The human body is made up of about 60% water.", "category": "biology" },
    { "_id": "rec47", "chunk_text": "The Industrial Revolution transformed manufacturing and transportation.", "category": "history" },
    { "_id": "rec48", "chunk_text": "Vincent van Gogh painted Starry Night.", "category": "art" },
    { "_id": "rec49", "chunk_text": "Airplanes fly due to the principles of lift and aerodynamics.", "category": "physics" },
    { "_id": "rec50", "chunk_text": "Renewable energy sources include wind, solar, and hydroelectric power.", "category": "energy" }
]
Upsert the sample dataset into a namespace in the index. Because the index is integrated with an embedding model, provide the textual statements and Pinecone converts them to dense vectors automatically. 
# Get an Index client for the index we created
dense_index = pc.Index(name=index_name)

# Upsert records into a namespace
dense_index.upsert_records(
    namespace="example-namespace",
    records=records
)

​
Step 5: Check index stats

Pinecone is eventually consistent, so there can be a slight delay before new or changed records are visible to queries. View index stats to check whether the current vector count matches the number of upserted vectors (50): 
import time

# Wait for the upserted vectors to be indexed
time.sleep(10)

# View stats for the index
stats = dense_index.describe_index_stats()
stats
Search the dense index for ten records most semantically similar to the query Famous historical structures and monuments. Because the index is integrated with an embedding model, provide the query as text; Pinecone converts it to a dense vector automatically. 
def print_results(search_results):
    for hit in search_results['result']['hits']:
        print(f"id: {hit['_id']:<5} | score: {round(hit['_score'], 3):<5} | category: {hit['fields']['category']:<10} | text: {hit['fields']['chunk_text']:<50}")

from pinecone import SearchQuery, SearchRerank

# Define the query
query = "Famous historical structures and monuments"

# Search the dense index
results = dense_index.search(
    namespace="example-namespace",
    query=SearchQuery(
        top_k=10,
        inputs={'text': query}
    )
)

print_results(results)
Most results are about historical structures and monuments; however, a few unrelated statements rank high in the list, for example, statements about Shakespeare and renewable energy. To get a more accurate ranking, search again and this time rerank the initial results based on their relevance to the query.

​
Step 7: Improve results

Reranking results is one of the most effective ways to improve search accuracy and relevance, but there are many other techniques to consider. For example:
  • Filtering by metadata: When records contain additional metadata, limit the search to records matching a filter expression.
  • Hybrid search: Add lexical search to capture precise keyword matches (e.g., product SKUs, email addresses, domain-specific terms) in addition to semantic matches.
  • Chunking strategies: Chunk content in different ways to improve results. Consider factors like the length of the content, the complexity of queries, and how results will be used in the application.
# Search the dense index and rerank results
reranked_results = dense_index.search(
    namespace="example-namespace",
    query=SearchQuery(
        top_k=10,
        inputs={'text': query}
    ),
    rerank=SearchRerank(
        model="bge-reranker-v2-m3",
        top_n=10,
        rank_fields=["chunk_text"]
    )
)

print_results(reranked_results)
All relevant results about historical structures and monuments are now ranked highest.

​
Step 8: Pass the reranked results to Orq.ai

Once results are retrieved and optionally reranked from Pinecone, pass them into an Orq.ai Deployment for generation. Store the original user query in a variable: this is the input sent to Orq.ai under the query field. The cleaned and reranked chunks from Pinecone are passed under the retrievals field, allowing Orq.ai to use them as contextual support for generation. This is what the system and user prompt look like configured in Orq.ai: Orq.ai Deployment editor showing the system and user prompt configured for the Pinecone RAG workflow 
chunk_texts = [hit['fields']['chunk_text'] for hit in reranked_results['result']['hits']]

retrievals = "\n".join(chunk_texts)  # Use ". ".join(...) for sentence-style joining
Then invoke the Orq.ai Deployment, passing the query and joined chunks as inputs: 
generation = client.deployments.invoke(
  key="pinecone-test",
  context={
    "environments": []
  },
  inputs={
    "query": query,
    "retrievals": retrievals
  },
  metadata={
    "custom-field-name": "custom-metadata-value"
  }
)

print(generation.choices[0].message.content)

​
Next steps

Pinecone is now connected to an Orq.ai Deployment with external retrieval results passed into a live workflow. This pattern works the same way with any external vector database. Retrieve the most relevant chunks, pass them as context, and let Orq.ai handle generation and orchestration. To improve and scale this setup inside Orq.ai:
  • Use RAGAS inside Orq.ai to evaluate the quality of retrieved chunks before they reach the model. This helps understand whether the retrieval step is improving model output quality.
  • Connect other vector databases such as Qdrant or Weaviate using the same interface
  • Experiment with prompt variations and test their impact using Orq.ai’s built-in Evaluators
  • Version, deploy, and monitor pipelines using Orq.ai’s production features
To skip external setup entirely, use Orq.ai’s fully hosted vector database, powered by Pinecone. It handles embedding, indexing, and retrieval out of the box, freeing focus on designing great applications. For more examples and integrations, visit the Orq.ai documentation.