Quick Start

Welcome to OneNode! The chillest AI-native database out there! Get started instantly without any setup or signup - just install the SDK and start saving documents. Whether you're prototyping, learning, or exploring our features, you can begin using OneNode immediately.

Step 1: Install SDK

pip install onenode

Step 2: Initialize the Client

Choose how you want to initialize OneNode based on your needs:

Option A: Without API Key (Temporary Data/Prototyping)

No environment variables, no API keys, no configuration - just start using OneNode immediately. Completely free with no signup required:

from onenode import OneNode, Text, Image

# Initialize client in anonymous mode - works instantly!
client = OneNode()
db = client.db("your_database")
collection = db.collection("your_collection")

Option B: With API Key (Persistent Data)

For production applications and persistent data, initialize with your API key. Free to use - just sign up to generate your API key:

from onenode import OneNode, Text, Image
import os

# Initialize client with API key
client = OneNode(api_key="your_api_key_here")
# Or use environment variable
# client = OneNode(api_key=os.getenv("ONENODE_API_KEY"))

db = client.db("your_database")
collection = db.collection("your_collection")

ℹ️ Anonymous vs API Key Usage

Anonymous Mode (Option A): Perfect for prototyping, learning, and testing. Data is temporary and automatically cleaned up. Completely free with no signup required - works instantly!
API Key Mode (Option B): Required for production applications. Data persists permanently, higher rate limits, access to advanced features like the developer console. Free to use - just requires signup to generate API key.

Step 3: Save Documents

Example: Insert a Document

# Create text instance
background_text = Text(
    "Through the Looking-Glass follows Alice as she steps into a fantastical world..."
).enable_index()

# Create image instance (file type auto-detected from extension)
profile_image = Image("alice-profile.jpg").enable_index()

# Define the document to be inserted
docs = [
    {
        "name": "Alice",
        "age": "7",
        "background": background_text,
        "profile_picture": profile_image,
    }
]

# Make the POST request to insert the document
response = collection.insert(docs)
print("Document inserted successfully!")

Step 4: Querying the Data

Built-in Semantic Search

Here's how to perform a query using Python:

query = "Alice in a fantastical world"
filter_dict = {"category": "fiction"}  # Optional
projection = {"mode": "include", "fields": ["title", "content"]}  # Optional

matches = collection.query(query, filter_dict, projection)

# Access results using attribute-style syntax
for match in matches:
    print(f"Match: {match.chunk} (Similarity Score: {match.score})")
    print(f"Document: {match.document}")

Traditional Search

For non-semantic, traditional database queries, use the find method. This works just like MongoDB queries and is perfect for exact matches, filtering by specific values, and structured data retrieval.

Here's how to perform traditional search using Python:

filter_dict = {"name": "Alice"}  # Simple filter
projection = {"mode": "include", "fields": ["name", "age"]}  # Optional
sort = {"age": -1}  # Optional

results = collection.find(filter_dict, projection, sort)

# Process results
for document in results:
    print(f"Found: {document}")

Traditional vs Semantic Search

Choose the right method for your use case:

Traditional search (find): Perfect for exact matches, filtering by known values, structured queries, and when you need predictable results.
Semantic search (query): Ideal for finding content by meaning, natural language queries, and discovering related information even when exact keywords don't match.