Quickstart

This guide helps you set up your emno vector database in just a few minutes.

Before you begin

Sign Up: If you haven't already, sign up for a free emno account.

On the free Hacker plan, you get one project and two collections, ideal for testing emno and running small applications. You can easily upgrade when you are ready.

1. Get your API Keys

Your API requests are authenticated using API keys. Any request that doesn't include an API key will return an error.

You can generate an API key from your dashboard at any time.

Open the emno dashboard.
Go to 'API Keys'.
Create an API Key and copy it.

2. Install the emno client

To connect with our API, we recommend using one of our official libraries. Currently we support a Node.js client. Alternatively, you're welcome to interact with the API directly if that's more your style.

# Install via NPM
npm install @emno/sdk

Good to know: When using the API directly, remember that each HTTP request should include a 'Token' header with your API key as value. You'll notice this in all our upcoming curl examples.

3. Initialize your connection

Set up your client connection to emno with your API key:

import { Emno } from '@emno/sdk';

const emno = new Emno({
    token: 'your_api_key',
});

4. Create a Collection

In emno, vector embeddings are stored into collections. In each collection, vectors have consistent dimensions and use the same metric to measure similarity.

For instance, you can create a "demoCollection" collection for nearest-neighbor searches, using the Cosine distance metric with vectors of 384 dimensions.

await emno.createCollection({
    name: 'demoCollection',
    config: {
        dim: 384,
        model: 'HUGGINGFACE-MINI-LM-L6',
        algo: "cosine"
        // additional optional configuration parameters
    },
});

# Set your API key and collection name (replace with actual values)
EMNO_API_KEY="your_api_key"
COLLECTION_NAME="your_collection_name"  # Replace with demoCollection for this example

# JSON data for creating the collection
json_data='{
  "name": "'"$COLLECTION_NAME"'",
  "config": {
    "dim": 384,
    "model": "HUGGINGFACE-MINI-LM-L6",
    "algo": "cosine"
  }
}'

# Make the POST request to create the collection
curl --request POST \
  --url "https://apis.emno.io/collections" \
  --header "Content-Type: application/json" \
  --header "Token: $EMNO_API_KEY" \
  --data "$json_data"

import requests

# Set your API key and collection name (replace with actual values)
EMNO_API_KEY = "your_api_key"
COLLECTION_NAME = "your_collection_name"  # Replace with demoCollection for this example

# JSON data for creating the collection
payload = {
    "name": COLLECTION_NAME,
    "config": {
        "dim": 384,
        "model": "HUGGINGFACE-MINI-LM-L6",
        "algo": "cosine"
    }
}

# Headers for the POST request
headers = {
    "Content-Type": "application/json",
    "Token": EMNO_API_KEY
}

# URL for the POST request
url = "https://apis.emno.io/collections"

# Make the POST request to create the collection
response = requests.post(url, json=payload, headers=headers)

# Print the response (optional)
print(response.json())

5. Insert Vectors

Once your collection is set, insert some sample vectors:

Create a client instance that gets the "demoCollection" collection:

const demoCollection = await emno.getCollection('demoCollection');

# Set your API key and collection name (replace with actual values)
EMNO_API_KEY="your_api_key"
COLLECTION_NAME="your_collection_name"

# Make the GET request to fetch collection details
response=$(curl --request GET \
  --url "https://apis.emno.io/collections/$COLLECTION_NAME" \
  --header "Token: $EMNO_API_KEY")

# Parse the JSON response using jq and extract the collectionId for further requests
COLLECTION_ID=$(echo "$response" | jq -r '.id')

# Print the collectionId
echo "Collection ID: $COLLECTION_ID"

import requests

# Set your API key and collection name (replace with actual values)
EMNO_API_KEY = "your_api_key"
COLLECTION_NAME = "your_collection_name"


# URL for the GET request
url = f"https://apis.emno.io/collections/{COLLECTION_NAME}"

# Headers for the GET request
headers = {
    "Token": EMNO_API_KEY
}

# Make the GET request to fetch collection details
response = requests.get(url, headers=headers)

# Parse the JSON response and extract the collectionId
collection_id = response.json().get('id')

# Print the collectionId (optional)
print("Collection ID:", collection_id)

Insert vectors to the collection:

await demoCollection.addText([{
        metadata: {
            source: "user_feedback"
        },
        content: 'The quick brown fox jumps over the lazy dog'
    },
    {
        metadata: {
            source: "user_feedback"
        },
        content: 'Customer service was friendly and solved my issue quickly'
    },
    {
        metadata: {
            source: "article"
        },
        content: 'Sustainable energy solutions are key to future environmental stability'
    },
    {
        metadata: {
            source: "article"
        },
        content: 'Blockchain technology is revolutionizing digital security'
    },
    {
        metadata: {
            source: "news"
        },
        content: 'Global markets react positively to the new economic stimulus package'
    }
]);
const allVectors = await demoCollection.listVectors();
console.log(allVectors);

# Set your API key and collection ID (replace with actual values)
EMNO_API_KEY="your_api_key"
COLLECTION_ID="your_collection_id"  # Replace with the actual COLLECTION_ID from the previous step

# JSON data for vector creation
json_data='[
    {
        "metadata": {
            "source": "user_feedback"
        },
        "content": "The quick brown fox jumps over the lazy dog"
    },
    {
        "metadata": {
            "source": "user_feedback"
        },
        "content": "Customer service was friendly and solved my issue quickly"
    },
    {
        "metadata": {
            "source": "article"
        },
        "content": "Sustainable energy solutions are key to future environmental stability"
    },
    {
        "metadata": {
            "source": "article"
        },
        "content": "Blockchain technology is revolutionizing digital security"
    },
    {
        "metadata": {
            "source": "news"
        },
        "content": "Global markets react positively to the new economic stimulus package"
    }
]'

# Make the POST request to create vectors
curl --request POST \
  --url "https://apis.emno.io/collections/$COLLECTION_ID/vectors/create/text" \
  --header "Content-Type: application/json" \
  --header "Token: $EMNO_API_KEY" \
  --data "$json_data"

import requests

# Set your API key and collection ID (replace with actual values)
EMNO_API_KEY = "your_api_key"
COLLECTION_ID = "your_collection_id"  # Replace with the actual COLLECTION_ID from the previous step

# JSON data for vector creation
payload = [
    {
        "metadata": {
            "source": "user_feedback"
        },
        "content": "The quick brown fox jumps over the lazy dog"
    },
    {
        "metadata": {
            "source": "user_feedback"
        },
        "content": "Customer service was friendly and solved my issue quickly"
    },
    {
        "metadata": {
            "source": "article"
        },
        "content": "Sustainable energy solutions are key to future environmental stability"
    },
    {
        "metadata": {
            "source": "article"
        },
        "content": "Blockchain technology is revolutionizing digital security"
    },
    {
        "metadata": {
            "source": "news"
        },
        "content": "Global markets react positively to the new economic stimulus package"
    }
]

# Headers for the POST request
headers = {
    "Content-Type": "application/json",
    "Token": EMNO_API_KEY
}

# URL for the POST request
url = f"https://apis.emno.io/collections/{COLLECTION_ID}/vectors/create/text"

# Make the POST request to create vectors
response = requests.post(url, json=payload, headers=headers)

# Print the response (optional)
print(response.json())

Note: When adding/updating a large volume of data, the standard practice is to divide it into batches, and perform multiple insert/update operations. With emno, you don't have to worry about batching - emno takes care of that for you!

6. Run a query for Nearest-Neighbor Search

Run a query in your collection to find vectors that are similar. This example searches for the two nearest vectors to a given text. It uses the Cosine distance metric, the same one you chose when you created the collection.

const queryVectorArray = {
    content: ['technological advancements in energy and security'],
    topK: 2,
};
const queryResultsVectors = await demoCollection.queryByText(queryVectorArray);
console.log(queryResultsVectors);

// Returns:
// [
//     [
//       {
//         "id": "v1",
//         "metadata": {
//           "source": "article"
//         },
//         "content": "Blockchain technology is revolutionizing digital security",
//         "values": [],
//         "distance": 0.5721539258956909,
//         "_client": { .... }
//         "collectionId": "c1"
//       },
//       {
//         "id": "v2",
//         "metadata": {
//           "source": "article"
//         },
//         "content": "Sustainable energy solutions are key to future environmental stability",
//         "values": [],
//         "distance": 0.6308304071426392,
//         "_client": { .... },
//         "collectionId": "c1"
//       }
//     ]
//   ]

# Set your API key and collection ID (replace with actual values)
EMNO_API_KEY="your_api_key"
COLLECTION_ID="your_collection_id"

# JSON data for the POST request
json_data='{
  "content": ["technological advancements in energy and security"],
  "topK": 2
}'

# Make the POST request to query for text
curl --request POST \
  --url "https://apis.emno.io/collections/$COLLECTION_ID/query/text" \
  --header "Content-Type: application/json" \
  --header "Token: $EMNO_API_KEY" \
  --data "$json_data"

# Returns:
# [
#     [
#         {
#             "id": "v1",
#             "content": "Blockchain technology is revolutionizing digital security",
#             "metadata": {
#                 "source": "article"
#             },
#             "distance": 0.5829882621765137,
#             "score": 41.70117378234863
#         },
#         {
#             "id": "v2",
#             "content": "Sustainable energy solutions are key to future environmental stability",
#             "metadata": {
#                 "source": "article"
#             },
#             "distance": 0.632359504699707,
#             "score": 36.7640495300293
#         }
#     ]
# ]

import requests

# Set your API key and collection ID (replace with actual values)
EMNO_API_KEY = "your_api_key"
COLLECTION_ID = "your_collection_id"


# JSON data for the POST request
payload = {
    "content": ["technological advancements in energy and security"],
    "topK": 2
}

# Headers for the POST request
headers = {
    "Content-Type": "application/json",
    "Token": EMNO_API_KEY
}

# URL for the POST request
url = f"https://apis.emno.io/collections/{COLLECTION_ID}/query/text"

# Make the POST request to query for text
response = requests.post(url, json=payload, headers=headers)

# Print the response (optional)
print(response.json())

# Returns:
# [
#     [
#         {
#             "id": "v1",
#             "content": "Blockchain technology is revolutionizing digital security",
#             "metadata": {
#                 "source": "article"
#             },
#             "distance": 0.5829882621765137,
#             "score": 41.70117378234863
#         },
#         {
#             "id": "v2",
#             "content": "Sustainable energy solutions are key to future environmental stability",
#             "metadata": {
#                 "source": "article"
#             },
#             "distance": 0.632359504699707,
#             "score": 36.7640495300293
#         }
#     ]
# ]

7. Cleanup

To delete your "demoCollection":

await emno.deleteCollection('demoCollection');

# Set your API key and collection identifier (replace with actual values)
EMNO_API_KEY="your_api_key"
COLLECTION_ID="your_collection_id" # You can also use your collection name here 

# Make the DELETE request to delete the collection
curl --request DELETE \
  --url "https://apis.emno.io/collections/$COLLECTION_ID" \
  --header "Token: $EMNO_API_KEY"

import requests

# Set your API key and collection identifier (replace with actual values)
EMNO_API_KEY = "your_api_key"
COLLECTION_ID = "your_collection_id"  # You can also use your collection name here

# Headers for the DELETE request
headers = {
    "Token": EMNO_API_KEY
}

# URL for the DELETE request
url = f"https://apis.emno.io/collections/{COLLECTION_ID}"

# Make the DELETE request to delete the collection
response = requests.delete(url, headers=headers)

# Print the response (optional)
print(response.json())

Warning: Be careful when deleting a collection. Once you delete the collection, you will not be able to use it again.

Next Steps

With your emno account set, and a grasp on the essential operations, check out our examples showcasing the diverse applications of emno. Or, start inserting your own vector embeddings.

NextExamples

Last updated 1 year ago