Quick Start

Welcome to OneNode DB! Follow these steps to get started with our powerful API service. Whether you're inserting your first document or exploring our extended features, this guide will help you set up and make your first API request quickly.

Step 1: Sign Up

First, sign 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

After signing in, create an API key for 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 be displayed only once. Store it securely.

Step 3: Create a Collection

Now, create a collection to store your data.

In the sidebar, click on the Collection tab and use the plus (+) button to create a new collection.
Set the database name and collection name. The new collection will appear in the sidebar.
Click on the collection to view the Database ID (db_id), which you'll need for API requests.

Step 4: Set Up Your Python Environment

To interact with OneNode DB's API, you'll need to use a Collection URL pointing to a specific collection and include your API Key for authorization.

Collection URL

The Collection URL format:

collection_url = "https://api.onenode.ai/v1/db/{db_id}/collection/{collection_name}"

Replace {db_id} and {collection_name} with your specific database identifier and collection name. Set this variable at the start to simplify the code throughout the tutorial.

For example, if your database ID is 123abc and the collection name is my_collection:

collection_url = "https://api.onenode.ai/v1/db/123abc/collection/my_collection"

Setting the API Key in Python

Store your API Key as an environment variable for secure access:

import os
 
ONENODE_API_KEY = os.getenv('ONENODE_API_KEY')

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..."}}
}
 
# Make the POST request to insert the document
response = requests.post(f"{collection_url}/document", headers=headers, data=json.dumps(document))
 
# Check the response
if response.status_code == 200:
    print("Document inserted successfully:", response.json())
else:
    print("Failed to insert document:", response.text)

EmbText Data Type - What Happens After Saving

After successfully saving an EmbText data type, additional processing occurs under the hood:

The saved data will have an updated field called chunks in addition to the original fields @embText.text and @embText.emb_model. The chunks field will be a list of chunked text segments.
Although not directly visible in the EmbText fields, each chunk in the chunks list is vectorized and indexed in the vector database. This illustrates how OneNode DB abstracts the underlying data processing pipeline, providing a seamless experience for managing complex data types.

Here is an example of how the saved data might look in the database:

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

Each chunk in chunks has been processed and indexed, ensuring efficient querying and similarity searches.

Step 6: Querying the Data

Once you have saved your data, you can query it using OneNode DB's API.

To query the saved data, make a POST request to the following endpoint:

{collection_url}/document/query

Query Request

Include your API Key in the headers.
The request body should contain a query field with the text to search for.
Optionally, you can include a top_k parameter to control the maximum number of returned chunks (default is 10).
Optionally, you can add return_document set to true (default is false) to return a list of matched documents instead of chunks.

Here is an example of how to perform a query using Python:

# Define the query
query_body = {
    "query": "Alice in a fantastical world",
    "top_k": 5,  # Optional, default is 10
    "return_document": True  # Optional, set to true to return matched documents instead of chunks
}
 
# 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

Here is an example of a successful query response:

{
    "results": [
        {
            "document_id": "doc_12345",
            "chunk": "Through the Looking-Glass follows Alice",
            "score": 0.95
        },
        {
            "document_id": "doc_12345",
            "chunk": "as she steps into a fantastical world...",
            "score": 0.89
        }
    ]
}

If return_document is set to true, the response might look like this:

{
    "results": [
        {
            "document_id": "doc_12345",
            "document": {
                "name": "Alice",
                "age": "7",
                "background": {
                    "@embText": {
                        "text": "Through the Looking-Glass follows Alice as she steps into a fantastical world...",
                        "emb_model": "default_model",
                        "chunks": [
                            "Through the Looking-Glass follows Alice",
                            "as she steps into a fantastical world..."
                        ]
                    }
                }
            },
            "score": 0.95
        }
    ]
}

The system automatically embeds the query text and returns a list of the most relevant chunks or documents based on similarity, along with a relevance score for each result. You can control the number of returned results using the top_k parameter.

Security Recommendations

Do not hardcode your API Key. 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 questions, visit our [Help Center] or contact support.

Happy building!

Overview Insert