# How to Configure Slow Query Logging in Neomodel: A Complete Guide

> Configure slow query logging in Neomodel to identify performance bottlenecks. Set the threshold using get_config() or the NEOMODEL_SLOW_QUERIES environment variable. Optimize your Neo4j queries now.

- Repository: [Neo4j Contrib/neomodel](https://github.com/neo4j-contrib/neomodel)
- Tags: how-to-guide
- Published: 2026-03-08

---

**Set the `slow_queries` threshold (in seconds) using `get_config().slow_queries = 1.0` or the `NEOMODEL_SLOW_QUERIES` environment variable to log Cypher queries exceeding the specified execution time.**

Configuring slow query logging helps you identify performance bottlenecks in your Neo4j graph database interactions. In the `neo4j-contrib/neomodel` library, this feature is controlled through a single configuration option that measures query execution time against a customizable threshold.

## Understanding the `slow_queries` Configuration Option

The `slow_queries` option is a floating-point value representing the threshold in seconds. When a Cypher query's execution time meets or exceeds this value, Neomodel emits a log entry identifying the slow operation.

In [`neomodel/config.py`](https://github.com/neo4j-contrib/neomodel/blob/main/neomodel/config.py) (lines 144–149), the option is defined as a dataclass field:

```python
slow_queries: float = field(
    default=0.0, 
    metadata={
        "env_var": "NEOMODEL_SLOW_QUERIES", 
        "description": "Threshold in seconds for slow query logging (0 = disabled)"
    }
)

```

The default value of `0.0` disables the feature entirely. Validation logic at lines 204–206 ensures the value cannot be negative, raising a `ValueError` if you attempt to set a threshold below zero.

## Methods to Configure Slow Query Logging

### Using Environment Variables (Production Recommended)

For production deployments, set the `NEOMODEL_SLOW_QUERIES` environment variable before importing Neomodel:

```bash
export NEOMODEL_SLOW_QUERIES=0.5

```

```python
from neomodel import config

# The value is automatically loaded from the environment

print(config.SLOW_QUERIES)  # → 0.5

```

### Using the Modern Configuration API

New code should use the `get_config()` function to access the singleton configuration instance:

```python
from neomodel import get_config

cfg = get_config()
cfg.slow_queries = 2.0  # Log queries taking longer than 2 seconds

```

This approach provides direct access to the underlying dataclass without deprecation warnings.

### Using the Legacy Attribute (Deprecated)

The legacy module-level proxy still supports `config.SLOW_QUERIES`, but emits a `DeprecationWarning`:

```python
from neomodel import config

config.SLOW_QUERIES = 1.0

# DeprecationWarning: Setting config.SLOW_QUERIES is deprecated ...

```

While functional for backward compatibility, migrate to the modern API to avoid future breaking changes.

## How Slow Query Logging Works at Runtime

When a Cypher statement executes, Neomodel's query wrapper in [`neomodel/sync_/transaction.py`](https://github.com/neo4j-contrib/neomodel/blob/main/neomodel/sync_/transaction.py) measures the elapsed time. If the duration meets or exceeds `config.slow_queries`, the system logs a warning via Python's standard `logging` framework at the `WARNING` level.

The log entry includes the Cypher query text and the actual execution time, allowing you to identify specific performance issues.

To verify the configuration works:

```python
import logging
from neomodel import get_config, db

# Enable console logging

logging.basicConfig(level=logging.WARNING)

cfg = get_config()
cfg.slow_queries = 0.001  # 1ms threshold for demonstration

# This query will likely trigger the warning

db.cypher_query("MATCH (n) RETURN n LIMIT 10")

```

Expected output:

```

WARNING:neomodel:Slow query (0.0123 s): MATCH (n) RETURN n LIMIT 10

```

## Configuration Validation and Error Handling

The configuration system validates the `slow_queries` value to prevent invalid states. As implemented in [`neomodel/config.py`](https://github.com/neo4j-contrib/neomodel/blob/main/neomodel/config.py) (lines 204–206), attempting to set a negative threshold raises:

```python
ValueError: slow_queries must be non-negative

```

The test suite in [`test/test_config_modernization.py`](https://github.com/neo4j-contrib/neomodel/blob/main/test/test_config_modernization.py) (lines 32–53, 112, and 670) verifies this behavior, ensuring that:
- The default value is `0.0` (disabled)
- Negative assignments raise `ValueError`
- Runtime updates apply immediately to subsequent queries

## Summary

- **Slow query logging** in Neomodel uses the `slow_queries` configuration option, measured in seconds.
- **Default behavior** is disabled (`0.0`); set a positive float to enable logging for queries exceeding that duration.
- **Configuration methods** include the `NEOMODEL_SLOW_QUERIES` environment variable, the modern `get_config().slow_queries` API, and the deprecated `config.SLOW_QUERIES` attribute.
- **Runtime implementation** resides in [`neomodel/sync_/transaction.py`](https://github.com/neo4j-contrib/neomodel/blob/main/neomodel/sync_/transaction.py), emitting `WARNING` level logs through Python's standard logging framework.
- **Validation** prevents negative thresholds, raising `ValueError` for invalid inputs.

## Frequently Asked Questions

### What is the default value for slow query logging in Neomodel?

The default value is `0.0`, which disables the feature entirely. As defined in [`neomodel/config.py`](https://github.com/neo4j-contrib/neomodel/blob/main/neomodel/config.py), this default ensures no logging overhead occurs unless you explicitly configure a threshold.

### Can I change the slow query threshold at runtime?

Yes. You can modify `get_config().slow_queries` at any point during application execution, and the new threshold applies immediately to subsequent Cypher queries. This allows dynamic adjustment based on operational conditions without restarting your application.

### Why am I seeing a DeprecationWarning when setting config.SLOW_QUERIES?

The `config.SLOW_QUERIES` attribute is part of Neomodel's legacy configuration API. While it remains functional for backward compatibility, the library emits a `DeprecationWarning` to encourage migration to the modern `get_config().slow_queries` interface, which provides direct access to the underlying configuration dataclass.

### What log level does Neomodel use for slow query warnings?

Neomodel emits slow query warnings at the `WARNING` level using Python's standard `logging` framework. The log message includes the execution duration and the Cypher query text, allowing you to identify performance bottlenecks in your Neo4j interactions.