> For the complete documentation index, see [llms.txt](https://docs.envector.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.envector.io/1.4.x/get-started/quick-start.md).

# Quick Start

This page offers two quick paths:

* Path A: Minimal — insert and search with the simplest API
* Path B: Full Crypto Cycle — explicit key generation, vector encryption, scoring, decryption, top‑k

Tip: An index is a logical collection of same‑dimension vectors with optional metadata — think of it like a table in an RDBMS.

## Path A — Minimal (Insert & Search)

Try the full Path A flow directly in Colab: [Quick Start (Path A) Notebook](https://colab.research.google.com/drive/1PnqGi4jQ3WSHhwD27LhXM56w1oYIPbv9?usp=sharing).

{% stepper %}
{% step %}
**Install SDK**

```bash
# Create & activate a virtual environment
python -m venv ev-env
source ev-env/bin/activate

# Install client SDK
pip install pyenvector
```

{% endstep %}

{% step %}
**Initialize**

```python
import pyenvector as ev

ev.init(address="localhost:50050", key_path="keys", key_id="quickstart")
```

{% endstep %}

{% step %}
**Create Index**

```python
index = ev.create_index("my_ev_index", dim=512)
```

{% endstep %}

{% step %}
**Insert Vectors**

You can pass plaintext vectors; the SDK encrypts them before sending so the server never sees plaintext.

```python
import numpy as np

vecs = np.random.rand(10, 512)
vecs = vecs / np.linalg.norm(vecs, axis=1, keepdims=True)  # normalize for IP
metadata = [f"Item {i+1}" for i in range(10)]

index.insert(vecs, metadata)
```

{% endstep %}

{% step %}
**Search**

`search()` performs: (1) encrypted scoring on the server, (2) client‑side decrypt, (3) top‑k metadata retrieval.

```python
search_index = ev.Index("my_ev_index")
query = vecs[0]
results = search_index.search(query, top_k=3, output_fields=["metadata"])[0]
print(results)
```

> Scoring = server‑side encrypted similarity; decrypt + top‑k complete the search on the client.
> {% endstep %}
> {% endstepper %}

***

## Path B — Explicit Crypto Cycle

Prefer to explore this more advanced flow interactively? Use the Colab notebook: [Explicit Crypto Cycle (Path B) Notebook](https://colab.research.google.com/drive/1jsPBvYv7VDA_ZeH8hs1971ejiB1nStXZ?usp=sharing).

{% stepper %}
{% step %}
**Install + Connect**

```python
import pyenvector as ev

# Connect only (no auto key setup)
ev.init_connect(address="localhost:50050")
```

{% endstep %}

{% step %}
**Generate Keys**

```python
from pyenvector.crypto import KeyGenerator

# Generate keys locally under key_dir = keys/crypto-qs
keygen = KeyGenerator(
    key_path=f"{key_path}/{key_id}",
    eval_mode="mm32",
    preset="ip2",
    metadata_encryption=True,
)
keygen.generate_keys()
```

{% endstep %}

{% step %}
**Init Index Config**

```python
# Point SDK to the generated keys; avoid auto generation
ev.init_index_config(
    key_path="keys",
    key_id="crypto-qs",
    auto_key_setup=False,
    metadata_encryption=True,
)
```

{% endstep %}

{% step %}
**Register Key**

```python
# Register and load the key on the server
ev.register_key(key_id="crypto-qs")
ev.load_key(key_id="crypto-qs")
```

{% endstep %}

{% step %}
**Create Index**

```python
# Create an index bound to the registered key config
index = ev.create_index("crypto_qs_index", dim=512)
```

{% endstep %}

{% step %}
**Encrypt Items + Insert**

```python
import numpy as np
from pyenvector.crypto import Cipher

vecs = np.random.rand(10, 512)
vecs = vecs / np.linalg.norm(vecs, axis=1, keepdims=True)
metadata = [f"Item {i+1}" for i in range(10)]

cipher = Cipher(dim=512, enc_key_path="keys/crypto-qs/EncKey.json")

# Explicitly encrypt each item (vector) before sending
enc_vectors = cipher.encrypt(vecs, "item")
print("Encrypted Vectors\n", enc_vectors)

# Explicitly encrypt metadata
enc_metadata = encrypt_metadata(metadata, key_path=metadata_key_path)
print("Encrypted Metadata\n", enc_metadata)

# Insert encrypted items with metadata
index.insert(enc_vectors, enc_metadata, request_ids=request_ids, execute_until="segmentation", load=True, await_completion=True)
```

> `cipher.encrypt(...)` accepts either a single 1D vector or a batch (2D `np.ndarray` / list of vectors) and returns a `CipherBlock` (or a list of `CipherBlock`s when the batch exceeds the internal split size).
> {% endstep %}

{% step %}
**Scoring**

```python
search_index = ev.Index("crypto_qs_index")

# Prepare query
query = vecs[0]

# Server performs encrypted similarity scoring; response is encrypted
encrypted_scores = search_index.scoring(query)[0]
```

{% endstep %}

{% step %}
**Decrypt + Top‑k**

```python
sec_key_path = "keys/crypto-qs/SecKey.json"
scores = cipher.decrypt_score(encrypted_scores, sec_key_path=sec_key_path)

topk = search_index.get_topk_metadata_results(scores, top_k=3, output_fields=["metadata"])
print(topk)
```

{% endstep %}
{% endstepper %}

References

* Search overview: [Search](/1.4.x/sdk-user-guide/search.md)
* Query encryption vs plaintext: [Scoring](/1.4.x/sdk-user-guide/search/scoring.md)
* Key generation details: [Key Generation](/1.4.x/sdk-user-guide/key/key-generation.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.envector.io/1.4.x/get-started/quick-start.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.