Quick Start for Python

Welcome to OneNode DB! This guide will help you get started quickly with our powerful API service. Whether you're inserting your first document or exploring advanced features, you'll find everything you need to make your first API request in just a few simple steps.

Step 1: Sign Up

Start by signing up for OneNode DB:

Visit OneNode DB Sign Up (opens in a new tab).
After signing up, log in and navigate to /dashboard, your main hub for managing databases, collections, and API keys.

Step 2: Create an API Key

Next, create an API key to authenticate your project:

In the sidebar, go to the API Key page.
Click to create a new API key—you can optionally name the key.
The key will only be displayed once. Store it securely.

Step 3: Create a Collection

To start storing your data, follow these steps to create a collection:

In the sidebar, click the Collection tab and use the plus (+) button to create a new collection.
Enter a database name and a collection name. Once created, the new collection will appear in the sidebar.
From the collection list in the sidebar, select the collection you just created.
Navigate to the Connect tab within the collection page to find the collection URL for the collection and access various APIs.

Step 4: Use Your API Key and Collection URL in Python

To interact with OneNode DB's API, you'll need a collection URL and your API Key for authorization.

Setting the API Key and Collection URL in Python

For this quick start guide (non-production environment), directly assign your API key and collection URL to variables:

ONENODE_API_KEY = "your_api_key_here"
COLLECTION_URL = "your_collection_url_here"

⚠️

Important: Only hardcode credentials for local development.

In production, use environment variables or secure server-side logic for API Key and Collection URL to prevent unauthorized access and keep information secure.

Include it in your request headers:

headers = {
    "Authorization": f"Bearer {ONENODE_API_KEY}",
    "Content-Type": "application/json"
}

Step 5: Make Your First API Request

Example: Insert a Document

Use Python to insert a document into the collection:

import requests
import json
 
# Define the document to be inserted
document = {
    "name": "Alice",
    "age": "7",
    "background": {
        "@embText": {
            "text": "Through the Looking-Glass follows Alice as she steps into a fantastical world...",
            "emb_model": "text-embedding-3-small"  # Optional, explicitly specifying the embedding model
        }
    }
}
 
# Wrap the document in a list under the 'documents' field
data = {
    "documents": [document]
}
 
# Make the POST request to insert the document
response = requests.post(f"{COLLECTION_URL}/document", headers=headers, data=json.dumps(data))
 
# Check the response
if response.status_code == 200:
    print("Document inserted successfully:", response.json())
else:
    print("Failed to insert document:", response.text)

EmbJSON - What Happens After Saving

When saving an EmbText data type, OneNode DB performs additional processing:

The saved data will have an updated field called chunks in addition to @embText.text and @embText.emb_model.
Each chunk is vectorized and indexed in the database, enabling efficient querying and similarity searches.

Here's an example of the saved data:

{
  "name": "Alice",
  "age": "7",
  "background": {
    "@embText": {
      "text": "Through the Looking-Glass follows Alice as she steps into a fantastical world...",
      "emb_model": "text-embedding-3-small",
      "chunks": [
        "Through the Looking-Glass follows Alice",
        "as she steps into a fantastical world..."
      ]
    }
  }
}

Complete Python Code for Inserting a Document

Here is the complete Python code to insert a document, including setting up the API key and headers:

import requests
import json
 
# Set the API key (non-production setup)
ONENODE_API_KEY = "your_api_key_here"
 
# Set the collection URL
COLLECTION_URL = "your_collection_url_here"
 
# Set the headers
headers = {
    "Authorization": f"Bearer {ONENODE_API_KEY}",
    "Content-Type": "application/json"
}
 
# Define the document to be inserted
document = {
    "name": "Alice",
    "age": "7",
    "background": {
        "@embText": {
            "text": "Through the Looking-Glass follows Alice as she steps into a fantastical world...",
            "emb_model": "text-embedding-3-small"  # Optional, explicitly specifying the embedding model
        }
    }
}
 
# Wrap the document in a list under the 'documents' field
data = {
    "documents": [document]
}
 
# Make the POST request to insert the document
response = requests.post(f"{COLLECTION_URL}/document", headers=headers, data=json.dumps(data))
 
# Check the response
if response.status_code == 200:
    print("Document inserted successfully:", response.json())
else:
    print("Failed to insert document:", response.text)

Step 6: Querying the Data

To retrieve data based on semantic similarity, make a POST request to:

{COLLECTION_URL}/document/query

Query Request

Include your API Key in the headers.
The request body should contain a query field, with optional emb_model, top_k, and filter parameters.
The filter parameter is a dictionary that allows you to narrow down the documents to be queried. OneNode DB supports all filter types that are supported by MongoDB, using the same format. When a filter is provided, the query will target only the documents that match the filter criteria.
You can visit the /filter page in the documentation for more details on the filter syntax.

Here's how to perform a query using Python:

import requests
import json
 
# Set the API key (non-production setup)
ONENODE_API_KEY = "your_api_key_here"
 
# Set the collection URL
COLLECTION_URL = "your_collection_url_here"
 
# Set the headers
headers = {
    "Authorization": f"Bearer {ONENODE_API_KEY}",
    "Content-Type": "application/json"
}
 
# Define the query
query_body = {
    "emb_model": "text-embedding-3-small",  # Optional, default is 'text-embedding-3-small'
    "query": "Alice in a fantastical world",
    "top_k": 5,  # Optional, default is 10
    "filter": {  # Optional filter to narrow down the documents
        "age": "7"
    }
}
 
# Make the POST request to query the document
query_response = requests.post(f"{COLLECTION_URL}/document/query", headers=headers, data=json.dumps(query_body))
 
# Check the response
if query_response.status_code == 200:
    print("Query results:", query_response.json())
else:
    print("Failed to query document:", query_response.text)

Example Response

Successful query response:

{
  "matches": [
    {
      "document_id": { "$oid": "671bf91580bffb6387b4f3d2" },
      "path": "background",
      "chunk": "Through the Looking-Glass follows Alice as she steps into a fantastical world...",
      "chunk_n": 0,
      "score": 0.703643203
    }
  ]
}

Complete Python Code for Querying Data

Here is the complete Python code to perform a query, including setting up the API key and headers:

import requests
import json
 
# Set the API key (non-production setup)
ONENODE_API_KEY = "your_api_key_here"
 
# Set the collection URL
COLLECTION_URL = "your_collection_url_here"
 
# Set the headers
headers = {
    "Authorization": f"Bearer {ONENODE_API_KEY}",
    "Content-Type": "application/json"
}
 
# Define the query
query_body = {
    "emb_model": "text-embedding-3-small",  # Optional, default is 'text-embedding-3-small'
    "query": "Alice in a fantastical world",
    "top_k": 5,  # Optional, default is 10
    "filter": {  # Optional filter to narrow down the documents
        "age": "7"
    }
}
 
# Make the POST request to query the document
query_response = requests.post(f"{COLLECTION_URL}/document/query", headers=headers, data=json.dumps(query_body))
 
# Check the response
if query_response.status_code == 200:
    print("Query results:", query_response.json())
else:
    print("Failed to query document:", query_response.text)

Feel free to let me know if there’s anything specific you’d like to add or clarify further in this documentation!

Security Recommendations

Do not hardcode your API Key in production environment. Use environment variables or secure configuration tools.
Keep your API Key private and do not share it publicly.

Next Steps

Experiment with more complex data types using OneNode's extended JSON.
Explore the full API documentation for more features.

If you have any questions, feel free to reach out to us at hello@onenode.ai.

Happy building!

Overview Insert