8. User properties

User properties are a way to attach metadata to specific connection. They are key-value pairs that can be used to store additional information, useful when you need a way to identify a connection for debugging or logging purposes.

Currently user properties can be set from QuasarDB Python API.

User properties are logged server side, when JSON log output is enabled. Information on how to enable JSON logging can be found here.

8.1. Identifying which connection is pushing data in small increments

Let’s say you have multiple applications writing data to same server. One of those applications is writing data in small increments.

This could impact server performance and is best to avoid when not using async pipelines. Lets use user properties to help identify troubling connection.

If your server is set to detect and log small increment writes, you can modify your applications to use unique user properties to identify which application is causing the issue.

8.2. Setting user properties from Python API and triggering logging for small increment writes

import quasardb
import datetime
import quasardb.pandas as qdbpd
import pandas as pd

data = {
    "column_1": [42]
}

idx = [datetime.datetime.now()]

df = pd.DataFrame(data, index=idx)

with quasardb.Cluster("qdb://127.0.0.1:2836") as conn:

    # first make sure that the user property is enabled
    conn.options().enable_user_properties()

    # now you can set user property
    conn.properties().put("application_id", "0")

    # write single row
    qdbpd.write_dataframe(df, conn, "t", create=True)

Now you should see in the server logs message for small increment coming from this connection.

{"timestamp":"2025-01-16T08:58:06.664698300Z","process_id":16548,"thread_id":33640,"level":"warning","message":"small incremental insert detected: append increased data size for shard t/0ms by only 0.012% (below threshold of 10%). This negatively affects write performance. To turn off this message, set 'log_small_append_percentage' to 0 in your qdbd config file.","$client_hostname":"hal-9000","$client_version":"3.14.2 3.14.2.dev0 d82b8b86d71c9334951b442b937abf9a598eda64 2025-01-14 10:18:10 -0500","$client_target":"AMD64 core2 64-bit","client_application_id":"0","$client_timestamp":"2025-01-16T09:58:06+01:00","$client_platform":"Microsoft Windows 11  (build 26100), 64-bit"}

With this information you can now identify which application is causing the issue and take appropriate action.

More examples for Python API can be found in Python API documentation.