# Configuration

## Configuration Overview

`ReID_Database` is configured with three parameters:

```python
from degirum_face.reid_database import ReID_DatabasePool

db = ReID_DatabasePool.get(
    db_path="./faces.lance",                  # Required: database location
    model_name="arcface_resnet100",           # Optional: model validation
    read_consistency_interval=0.5             # Optional: multi-process synchronization
)
```

**Typically initialized via FaceRecognizer/FaceTracker** - see [FaceRecognizer Configuration](/face-recognition/guides/overview/configuration.md) or [FaceTracker Configuration](/face-recognition/guides/overview-1/configuration.md).

***

## Parameters

### db\_path (required)

Path to the LanceDB database directory.

**Relative path:**

```python
db_path="./face_database.lance"
```

**Absolute path:**

```python
db_path="/var/lib/face_recognition/faces.lance"
```

**Windows path:**

```python
db_path="C:\\FaceRecognition\\Database\\faces.lance"
```

**Database structure:**

```
face_database.lance/
├── embeddings.lance/
├── attributes.lance/
├── images.lance/
└── _metadata.lance/
```

***

### model\_name (optional)

Embedding model name for validation. Ensures database only contains embeddings from compatible models.

**Example:**

```python
# Create database with model validation
db = ReID_DatabasePool.get(
    db_path="./faces.lance",
    model_name="arcface_resnet100"
)

# Later access validates model matches
db2 = ReID_DatabasePool.get(
    db_path="./faces.lance",
    model_name="arcface_resnet100"  # ✓ Matches
)

# Different model raises ValueError
db3 = ReID_DatabasePool.get(
    db_path="./faces.lance",
    model_name="facenet_512"  # ✗ Raises ValueError
)
```

**When to use:**

* Multi-model environments
* Preventing embedding pollution
* Database migration validation

**When to omit:**

* Single-model deployments
* Testing/development

***

### read\_consistency\_interval (optional)

Time interval in seconds for read consistency in multi-process scenarios. Controls how frequently database readers check for updates from writers.

**Use case:** When multiple processes access the same database - one process enrolling faces while others perform recognition/tracking.

**Example:**

```python
# Enrolling process (writer) - can use default
enroller_db = ReID_DatabasePool.get(
    db_path="./shared_faces.lance",
    model_name="arcface_resnet100"
    # read_consistency_interval not needed
)

# Tracking processes (readers) - refresh every 0.5 seconds
tracker_db = ReID_DatabasePool.get(
    db_path="./shared_faces.lance",
    model_name="arcface_resnet100",
    read_consistency_interval=0.5  # Check for new enrollments
)
```

**Recommended values:**

* `0.1-0.5` - Real-time applications (low latency)
* `0.5-1.0` - General use (balanced)
* `1.0+` - Batch processing (lower overhead)
* `None` - Single process or default behavior

**When to use:**

* Multiple cameras/processes reading from shared database
* One process enrolling while others track
* Distributed face recognition systems

**When to omit:**

* Single-process applications
* Writer-only processes
* Read-only batch processing

***

## Initialization Patterns

### Using ReID\_DatabasePool (Recommended)

Connection pooling ensures single connection per database path:

```python
from degirum_face.reid_database import ReID_DatabasePool

# Get or create database instance
db = ReID_DatabasePool.get("./faces.lance")

# Subsequent calls return same instance
db2 = ReID_DatabasePool.get("./faces.lance")
assert db is db2  # Same connection

# Thread safety: Database objects are thread-safe
# Safe to obtain multiple references and use them concurrently
```

**Thread Safety:** Database objects returned by the pool are thread-safe. You can safely obtain multiple references to the same database object and use them concurrently from different threads.

### Using ReID\_Database Directly

Direct instantiation (bypasses connection pooling):

```python
from degirum_face.reid_database import ReID_Database

db = ReID_Database(
    db_path="./faces.lance",
    model_name="arcface_resnet100"  # Optional
)
```

**Warning:** Not recommended for production. Multiple instances for the same path can cause issues.

***

## Environment-Specific Paths

### Development

```python
# Local relative path
db = ReID_DatabasePool.get("./dev_faces.lance")
```

### Production

```python
# Persistent storage location
db = ReID_DatabasePool.get("/data/face_recognition/production.lance")

# Or use environment variable
import os
db_path = os.environ.get("FACE_DB_PATH", "./faces.lance")
db = ReID_DatabasePool.get(db_path)
```

### Docker/Container

```python
# Mount persistent volume to /data
db = ReID_DatabasePool.get("/data/faces.lance")
```

***

See [Methods Reference](/face-recognition/guides/overview-3/methods.md) for database operations.


---

# Agent Instructions: 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:

```
GET https://docs.degirum.com/face-recognition/guides/overview-3/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.