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.
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 NPMnpm install @emno/sdk
# Install via pip
<Coming Soon!>
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:
# Python client coming soon. # For now, we will use the "requests" library for all subsequent stepspip install requests
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.
# 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 collectionjson_data='{ "name": "'"$COLLECTION_NAME"'", "config": { "dim": 384, "model": "HUGGINGFACE-MINI-LM-L6", "algo": "cosine" }}'# Make the POST request to create the collectioncurl--requestPOST \--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 collectionpayload ={"name": COLLECTION_NAME,"config":{"dim":384,"model":"HUGGINGFACE-MINI-LM-L6","algo":"cosine"}}# Headers for the POST requestheaders ={"Content-Type":"application/json","Token": EMNO_API_KEY}# URL for the POST requesturl ="https://apis.emno.io/collections"# Make the POST request to create the collectionresponse = 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:
# 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 detailsresponse=$(curl--requestGET \--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 requestsCOLLECTION_ID=$(echo"$response"|jq-r'.id')# Print the collectionIdecho"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 requesturl =f"https://apis.emno.io/collections/{COLLECTION_NAME}"# Headers for the GET requestheaders ={"Token": EMNO_API_KEY}# Make the GET request to fetch collection detailsresponse = requests.get(url, headers=headers)# Parse the JSON response and extract the collectionIdcollection_id = response.json().get('id')# Print the collectionId (optional)print("Collection ID:", collection_id)
Insert vectors to the collection:
awaitdemoCollection.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' }]);constallVectors=awaitdemoCollection.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 creationjson_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 vectorscurl--requestPOST \--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 creationpayload = [{"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 requestheaders ={"Content-Type":"application/json","Token": EMNO_API_KEY}# URL for the POST requesturl =f"https://apis.emno.io/collections/{COLLECTION_ID}/vectors/create/text"# Make the POST request to create vectorsresponse = 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.
constqueryVectorArray= { content: ['technological advancements in energy and security'], topK:2,};constqueryResultsVectors=awaitdemoCollection.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 requestjson_data='{ "content": ["technological advancements in energy and security"], "topK": 2}'# Make the POST request to query for textcurl--requestPOST \--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 requestpayload ={"content": ["technological advancements in energy and security"],"topK":2}# Headers for the POST requestheaders ={"Content-Type":"application/json","Token": EMNO_API_KEY}# URL for the POST requesturl =f"https://apis.emno.io/collections/{COLLECTION_ID}/query/text"# Make the POST request to query for textresponse = 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 collectioncurl--requestDELETE \--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 requestheaders ={"Token": EMNO_API_KEY}# URL for the DELETE requesturl =f"https://apis.emno.io/collections/{COLLECTION_ID}"# Make the DELETE request to delete the collectionresponse = 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.