Configuration

Configuration Overview

ReID_Database is configured with three parameters:

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 or FaceTracker Configuration.

---

Parameters

db_path (required)

Path to the LanceDB database directory.

Relative path:

db_path="./face_database.lance"

Absolute path:

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

Windows path:

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:

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

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

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):

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

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

Production

# 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

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

---

See Methods Reference for database operations.