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

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 (lines 144–149), the option is defined as a dataclass field:

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:

export NEOMODEL_SLOW_QUERIES=0.5

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:

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:

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

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 (lines 204–206), attempting to set a negative threshold raises:

ValueError: slow_queries must be non-negative

The test suite in 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, 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}