> ## Documentation Index
> Fetch the complete documentation index at: https://docs.camel-ai.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Camel.storages.vectordb storages.faiss

<a id="camel.storages.vectordb_storages.faiss" />

<a id="camel.storages.vectordb_storages.faiss.FaissStorage" />

## FaissStorage

```python theme={"system"}
class FaissStorage(BaseVectorStorage):
```

An implementation of the `BaseVectorStorage` using FAISS,
Facebook AI's Similarity Search library for efficient vector search.

The detailed information about FAISS is available at:
`FAISS <https://github.com/facebookresearch/faiss>`\_

**Parameters:**

* **vector\_dim** (int): The dimension of storing vectors.
* **index\_type** (str, optional): Type of FAISS index to create. Options include 'Flat', 'IVF', 'HNSW', etc. (default: :obj:`'Flat'`)
* **collection\_name** (Optional\[str], optional): Name for the collection. If not provided, set it to the current time with iso format. (default: :obj:`None`)
* **storage\_path** (Optional\[str], optional): Path to directory where the index will be stored. If None, index will only exist in memory. (default: :obj:`None`)
* **distance** (VectorDistance, optional): The distance metric for vector comparison (default: :obj:`VectorDistance.COSINE`)
* **nlist** (int, optional): Number of cluster centroids for IVF indexes. Only used if index\_type includes 'IVF'. (default: :obj:`100`)
* **m** (int, optional): HNSW parameter. Number of connections per node. Only used if index\_type includes 'HNSW'. (default: :obj:`16`) \*\*kwargs (Any): Additional keyword arguments.

**Note:**

* FAISS offers various index types optimized for different use cases:
* 'Flat': Exact search, but slowest for large datasets
* 'IVF': Inverted file index, good balance of speed and recall
* 'HNSW': Hierarchical Navigable Small World, fast with high recall
* 'PQ': Product Quantization for memory-efficient storage
* The choice of index should be based on your specific requirements
  for search speed, memory usage, and accuracy.

<a id="camel.storages.vectordb_storages.faiss.FaissStorage.__init__" />

### **init**

```python theme={"system"}
def __init__(
    self,
    vector_dim: int,
    index_type: str = 'Flat',
    collection_name: Optional[str] = None,
    storage_path: Optional[str] = None,
    distance: VectorDistance = VectorDistance.COSINE,
    nlist: int = 100,
    m: int = 16,
    **kwargs: Any
):
```

Initialize the FAISS vector storage.

**Parameters:**

* **vector\_dim**: Dimension of vectors to be stored
* **index\_type**: FAISS index type ('Flat', 'IVF', 'HNSW', etc.)
* **collection\_name**: Name of the collection (defaults to timestamp) (default: timestamp)
* **storage\_path**: Directory to save the index (None for in-memory only)
* **distance**: Vector distance metric
* **nlist**: Number of clusters for IVF indexes
* **m**: HNSW parameter for connections per node \*\*kwargs: Additional parameters

<a id="camel.storages.vectordb_storages.faiss.FaissStorage._generate_collection_name" />

### \_generate\_collection\_name

```python theme={"system"}
def _generate_collection_name(self):
```

Generates a collection name if user doesn't provide

<a id="camel.storages.vectordb_storages.faiss.FaissStorage._get_index_path" />

### \_get\_index\_path

```python theme={"system"}
def _get_index_path(self):
```

Returns the path to the index file

<a id="camel.storages.vectordb_storages.faiss.FaissStorage._get_metadata_path" />

### \_get\_metadata\_path

```python theme={"system"}
def _get_metadata_path(self):
```

Returns the path to the metadata file

<a id="camel.storages.vectordb_storages.faiss.FaissStorage._create_index" />

### \_create\_index

```python theme={"system"}
def _create_index(self):
```

**Returns:**

A FAISS index object configured according to the parameters.

<a id="camel.storages.vectordb_storages.faiss.FaissStorage._save_to_disk" />

### \_save\_to\_disk

```python theme={"system"}
def _save_to_disk(self):
```

Save the index and metadata to disk if storage\_path is provided.

<a id="camel.storages.vectordb_storages.faiss.FaissStorage._load_from_disk" />

### \_load\_from\_disk

```python theme={"system"}
def _load_from_disk(self):
```

Loads the index and metadata from disk if they exist.

<a id="camel.storages.vectordb_storages.faiss.FaissStorage.add" />

### add

```python theme={"system"}
def add(self, records: List[VectorRecord], **kwargs):
```

Adds a list of vectors to the index.

**Parameters:**

* **records** (List\[VectorRecord]): List of vector records to be added. \*\*kwargs (Any): Additional keyword arguments.

<a id="camel.storages.vectordb_storages.faiss.FaissStorage.update_payload" />

### update\_payload

```python theme={"system"}
def update_payload(
    self,
    ids: List[str],
    payload: Dict[str, Any],
    **kwargs: Any
):
```

Updates the payload of the vectors identified by their IDs.

**Parameters:**

* **ids** (List\[str]): List of unique identifiers for the vectors to be updated.
* **payload** (Dict\[str, Any]): Payload to be updated for all specified IDs. \*\*kwargs (Any): Additional keyword arguments.

<a id="camel.storages.vectordb_storages.faiss.FaissStorage.delete_collection" />

### delete\_collection

```python theme={"system"}
def delete_collection(self):
```

Deletes the entire collection (index and metadata).

<a id="camel.storages.vectordb_storages.faiss.FaissStorage.delete" />

### delete

```python theme={"system"}
def delete(
    self,
    ids: Optional[List[str]] = None,
    payload_filter: Optional[Dict[str, Any]] = None,
    **kwargs: Any
):
```

Deletes vectors from the index based on either IDs or payload
filters.

**Parameters:**

* **ids** (Optional\[List\[str]], optional): List of unique identifiers for the vectors to be deleted.
* **payload\_filter** (Optional\[Dict\[str, Any]], optional): A filter for the payload to delete points matching specific conditions. \*\*kwargs (Any): Additional keyword arguments.

**Note:**

* FAISS does not support efficient single vector removal for most
  index types. This implementation recreates the index without the
  deleted vectors, which can be inefficient for large datasets.
* If both `ids` and `payload_filter` are provided, both filters
  will be applied (vectors matching either will be deleted).

<a id="camel.storages.vectordb_storages.faiss.FaissStorage.status" />

### status

```python theme={"system"}
def status(self):
```

**Returns:**

VectorDBStatus: Current status of the vector database.

<a id="camel.storages.vectordb_storages.faiss.FaissStorage.query" />

### query

```python theme={"system"}
def query(
    self,
    query: VectorDBQuery,
    filter_conditions: Optional[Dict[str, Any]] = None,
    **kwargs: Any
):
```

Searches for similar vectors in the storage based on the provided
query.

**Parameters:**

* **query** (VectorDBQuery): The query object containing the search vector and the number of top similar vectors to retrieve.
* **filter\_conditions** (Optional\[Dict\[str, Any]], optional): A dictionary specifying conditions to filter the query results. \*\*kwargs (Any): Additional keyword arguments.

**Returns:**

List\[VectorDBQueryResult]: A list of query results ordered by
similarity.

<a id="camel.storages.vectordb_storages.faiss.FaissStorage.clear" />

### clear

```python theme={"system"}
def clear(self):
```

Remove all vectors from the storage.

<a id="camel.storages.vectordb_storages.faiss.FaissStorage.load" />

### load

```python theme={"system"}
def load(self):
```

Load the index from disk if storage\_path is provided.

<a id="camel.storages.vectordb_storages.faiss.FaissStorage.client" />

### client

```python theme={"system"}
def client(self):
```

Provides access to the underlying FAISS client.

<a id="camel.storages.vectordb_storages.faiss.FaissStorage._matches_filter" />

### \_matches\_filter

```python theme={"system"}
def _matches_filter(self, vector_id: str, filter_conditions: Dict[str, Any]):
```

Checks if a vector's payload matches the filter conditions.

**Parameters:**

* **vector\_id** (str): ID of the vector to check.
* **filter\_conditions** (Dict\[str, Any]): Conditions to match against.

**Returns:**

bool: True if the payload matches all conditions, False otherwise.

<a id="camel.storages.vectordb_storages.faiss.FaissStorage._normalize_vector" />

### \_normalize\_vector

```python theme={"system"}
def _normalize_vector(self, vector: 'ndarray'):
```

Normalizes a vector to unit length for cosine similarity.

**Parameters:**

* **vector** (ndarray): Vector to normalize, either 1D or 2D array.

**Returns:**

ndarray: Normalized vector with the same shape as input.