# Quickstart

## Before you begin

* **Sign Up:** If you haven't already, sign up for a free [emno account](https://emno.io/). 

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](https://emno.io/app). 
* 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](https://github.com/emnodb/sdk-js). Alternatively, you're welcome to interact with the [API directly](https://apis.emno.io/documentation) if that's more your style.

{% tabs %}
{% tab title="Javascript" %}

```javascript
# Install via NPM
npm install @emno/sdk
```

{% endtab %}

{% tab title="Python" %}

```
# Install via pip
<Coming Soon!>
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**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.
{% endhint %}

## 3. I**nitialize your connection**

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

{% tabs %}
{% tab title="Javascript" %}

<pre class="language-javascript"><code class="lang-javascript">import { Emno } from '@emno/sdk';

<strong>const emno = new Emno({
</strong>    token: 'your_api_key',
});
</code></pre>

{% endtab %}

{% tab title="Python" %}

```python
# Python client coming soon. 
# For now, we will use the "requests" library for all subsequent steps

pip install requests
```

{% endtab %}
{% endtabs %}

## 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.&#x20;

{% tabs %}
{% tab title="Javascript" %}

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

{% endtab %}

{% tab title="curl" %}

```bash
# 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"

```

{% endtab %}

{% tab title="Python" %}

```python
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())
```

{% endtab %}
{% endtabs %}

## 5. Insert Vectors

Once your collection is set, insert some sample vectors:

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

{% tabs %}
{% tab title="Javascipt" %}

<pre class="language-javascript"><code class="lang-javascript"><strong>const demoCollection = await emno.getCollection('demoCollection');
</strong></code></pre>

{% endtab %}

{% tab title="curl" %}

```sh
# 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"

```

{% endtab %}

{% tab title="Python" %}

```python
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)
```

{% endtab %}
{% endtabs %}

* Insert vectors to the collection:

{% tabs %}
{% tab title="Javascript" %}

```javascript
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);
```

{% endtab %}

{% tab title="curl" %}

```sh
# 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"
```

{% endtab %}

{% tab title="Python" %}

```python
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())

```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
**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!
{% endhint %}

## 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.

{% tabs %}
{% tab title="Javascript" %}

```javascript
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"
//       }
//     ]
//   ]
```

{% endtab %}

{% tab title="curl" %}

```sh
# 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
#         }
#     ]
# ]

```

{% endtab %}

{% tab title="Python" %}

```python
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
#         }
#     ]
# ]

```

{% endtab %}
{% endtabs %}

## 7. Cleanup

To delete your "demoCollection":

{% tabs %}
{% tab title="Javascript" %}

```
await emno.deleteCollection('demoCollection');
```

{% endtab %}

{% tab title="curl" %}

```sh
# 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"

```

{% endtab %}

{% tab title="Python" %}

```python
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())

```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
**Warning:** Be careful when deleting a collection. Once you delete the collection, you will not be able to use it again.&#x20;
{% endhint %}

## Next Steps

With your emno account set, and a grasp on the essential operations, check out [our examples](https://docs.emno.io/emno/getting-started/examples) showcasing the diverse applications of emno. Or, [start](https://emno.io/app) inserting your own vector embeddings.