# Configuring your app

## **Deploying and Configuring Qyver Server**

### **Application Structure and Configuration**

The core logic of a **Qyver-powered** application resides in **configuration files**, where you define its structure and behavior using the **Qyver framework**.

By default, all examples in this documentation use an **in-memory database**, which is ideal for **testing and prototyping**. For guidance on integrating **alternative vector databases**, refer to the Vector Database Documentation.

#### **Getting Started**

* Begin with a **basic example application** here.
* Explore a **real-world case study** in the Amazon example.
* For **advanced examples** on embedding spaces and queries, check out the Qyver Notebooks.

***

### **Understanding the Application's Core Components**

A functional Qyver application is structured around three key files:

**`index.py`** – Defines **schemas, spaces, and indices**.\
\&#xNAN;**`query.py`** – Specifies **queries** for searching and ranking results.\
\&#xNAN;**`api.py`** – Configures the **executor**, integrating all components.

***

#### **1. Defining Schema, Spaces, and Index (`index.py`)**

```python
from qyver import framework as sl

class YourSchema(sl.Schema):
    id: sl.IdField
    attribute: sl.String

your_schema = YourSchema()

model_name = "<your model name>"  # Replace with a valid model!
text_space = sl.TextSimilaritySpace(text=your_schema.attribute, model=model_name)

index = sl.Index(text_space)
```

In this file:

* A **schema** is defined to structure input data.
* A **space** is created, mapping an attribute to an embedding model.
* An **index** is established to store and retrieve embeddings efficiently.

**Modifications to this file** (e.g., adding new spaces or altering the schema) require **re-ingesting data**, as previous vectors will no longer be valid.

***

#### **2. Defining Queries (`query.py`)**

```python
from qyver import framework as sl
from .index import index, text_space, your_schema

query = (
    sl.Query(index)
    .find(your_schema)
    .similar(text_space.text, sl.Param("query_text"))
)
```

This file:

* Defines **queries** to search within the indexed data.
* Allows customization of **weights, limits, radius**, and other parameters.

***

#### **3. Configuring API and Executor (`api.py`)**

```python
from qyver import framework as sl
from .index import index, your_schema
from .query import query

your_source: RestSource = sl.RestSource(your_schema)
your_query = sl.RestQuery(sl.RestDescriptor("query"), query)

executor = sl.RestExecutor(
    sources=[your_source],
    indices=[index],
    queries=[your_query],
    vector_database=sl.InMemoryVectorDatabase(),
)

sl.QyverRegistry.register(executor)
```

This file:

* Sets up **data sources** to handle incoming data.
* Registers queries as **REST API endpoints** (e.g., `/api/v1/search/query`).
* Defines the **executor**, which connects sources, indices, queries, and vector storage.

**For detailed API documentation, check here.**

***

### **Data Loading & Ingestion**

Qyver supports **loading data from local or remote files** instead of requiring **manual REST API ingestion**.

#### **1. Creating a Data Loader**

```python
config = sl.DataLoaderConfig(
    "https://path-to-your-file.csv", 
    DataFormat.CSV, 
    "name_of_your_loader",
    pandas_read_kwargs={"sep": ";"}
)

data_loader_source = sl.DataLoaderSource(your_schema, config)

executor = sl.RestExecutor(
    sources=[your_source, data_loader_source], 
    indices=[index],
    queries=[sl.RestQuery(sl.RestDescriptor("query"), query)],
    vector_database=sl.InMemoryVectorDatabase(),
)
```

#### **2. Mapping Schema Fields to Columns**

```python
data_frame_parser = sl.DataFrameParser(
    your_schema, 
    mapping={your_schema.id: "id_field_name", your_schema.attribute: "custom_field_name"}
)

data_loader_source = sl.DataLoaderSource(your_schema, config, data_frame_parser)
```

#### **3. Handling Large Datasets with Chunking**

```python
# For CSV
config = sl.DataLoaderConfig(
    "https://path-to-your-file.csv", 
    DataFormat.CSV, 
    pandas_read_kwargs={"chunksize": 10000}
)

# For JSONL
config = sl.DataLoaderConfig(
    "https://path-to-your-file.jsonl", 
    DataFormat.JSON, 
    pandas_read_kwargs={"lines": True, "chunksize": 10000}
)
```

Chunking is essential for **efficient memory management** when working with **large datasets**.

***

### **Customizing API Endpoints**

By default, Qyver follows this API structure:

* **Query Endpoint:** `/api/v1/search/<query_name>`
* **Data Ingestion Endpoint:** `/api/v1/ingest/<schema_name>`

To **customize API paths**, modify the `RestEndpointConfiguration`:

```python
rest_endpoint_config = sl.RestEndpointConfiguration(
    query_path_prefix="retrieve",
    ingest_path_prefix="insert",
    api_root_path="/qyver/v3",
)

executor = sl.RestExecutor(
    sources=[your_source],
    indices=[index],
    queries=[sl.RestQuery(sl.RestDescriptor("query"), query)],
    vector_database=sl.InMemoryVectorDatabase(),
    rest_endpoint_config=rest_endpoint_config
)
```

***

### **Using Recency Space**

**Limitations:**\
1\. Recency embeddings are **not periodically updated** (coming soon!).\
2\. The **server's startup timestamp** is fixed at launch.

#### **Workaround for Fixed Timestamps**

```python
NOW = int(datetime(year=2024, month=1, day=2, tzinfo=UTC).timestamp())
EXECUTOR_DATA = {CONTEXT_COMMON: {CONTEXT_COMMON_NOW: NOW}}

executor = sl.RestExecutor(
    sources=[source], indices=[index],
    queries=[sl.RestQuery(sl.RestDescriptor("query"), query)],
    vector_database=sl.InMemoryVectorDatabase(),
    context_data=EXECUTOR_DATA
)
```

**Set the `DISABLE_RECENCY_SPACE` environment variable to `false` to enable it.**

***

### **Optimizing Performance with GPU Acceleration**

Qyver supports **GPU acceleration** for text and image embeddings, improving performance for **large-scale processing**.

#### **Enable GPU Acceleration**

Set the `GPU_EMBEDDING_THRESHOLD` environment variable:

```sh
export GPU_EMBEDDING_THRESHOLD=5000
```

* **Default:** `0` (Disabled)
* **Valid range:** `1-9999`
* **Behavior:** If the batch size exceeds the threshold, **GPU acceleration** is activated.

**Ensure:**

* Your system has an **NVIDIA GPU** (best performance with PyTorch).
* **GPU drivers** are up to date.

***

### **Final Thoughts**

Qyver simplifies **modular, scalable AI-powered search applications**, allowing **flexibility in deployment** with:&#x20;

* **Seamless integration** with REST APIs & Vector Databases
* **Efficient data ingestion** via REST or file-based sources
* **Advanced embedding techniques** for structured + unstructured data
* **Scalability optimizations**, including **GPU acceleration**

**Ready to build?**