Three decisions drive most production problems. The first is the partition key, which cannot be changed in place once a container exists. The second is the RU cost of each operation, since every read and write is billed in Request Units. The third is the consistency level, which trades read freshness against latency and availability.

The guide starts with an at-a-glance table. It then covers partition keys and hierarchical partition keys, hot partitions and data modeling, and RU and 429 handling with .NET SDK v3 code. After that come consistency levels, followed by anti-patterns, a production readiness checklist and a migration note. You will not find generic savings figures here. Instead, the guide shows you how to measure your own RU numbers, because the cost depends on your data and queries.

Before we start, you need an existing Cosmos DB for NoSQL account and the .NET SDK v3 (Microsoft.Azure.Cosmos). The current SDK version was not confirmed while writing, so check NuGet for the latest release.

Version note: This guide targets Azure Cosmos DB for NoSQL (a managed service with no user-facing version number, with features announced up to Build 2026 in June 2026) and the .NET SDK v3 (Microsoft.Azure.Cosmos), whose current version you should confirm on NuGet.

 

In this guide

• Cosmos DB Best Practices at a Glance
• Cosmos DB Partition Key Best Practices
• Fix a Cosmos DB Hot Partition with a Better Data Model
• Cosmos DB RU Optimization and 429 Throttling
• Cosmos DB Consistency Levels: Choose and Override
• Common Anti-Patterns, Operations and Production Readiness Checklist
• Key takeaways
• FAQ

Cosmos DB Best Practices at a Glance

Most Cosmos DB problems come from a weak partition key, expensive queries and the wrong consistency level. The table below sums up the rules for Cosmos DB cost optimization and performance.

Here is a quick reference of what to do and what to avoid in each area:

Each row is explained with its reason in the sections below.

In plain English: A Request Unit (RU) is one normalized currency for the CPU, IO and memory an operation needs. Think of it like a restaurant bill: reading one small item is a cheap dish, a large query is a full banquet, and your throughput is the budget per second.

Cosmos DB Partition Key Best Practices

Choose a partition key with high cardinality (many distinct values) that spreads both storage and RU use evenly and appears in your most common query filters. The key is hard to change later, so it deserves the most design time of any Cosmos DB decision.

What Is the Difference Between a Logical and a Physical Partition?

A logical partition holds all items that share the same partition key value, and it is limited to 20 GB. A physical partition is the storage and compute unit that hosts one or more logical partitions. You control the first, and Cosmos DB manages the second.

In plain English: Think of a library. Each logical partition is a shelf of labelled books, and each physical partition is a room that holds several shelves. You choose the labels, and the library decides which room each shelf goes in. Unlike a real shelf, a logical partition can never grow past its 20 GB limit.

How Do You Know a Partition Key Is Good?

A good key passes four checks. Test your candidate against each one before you create the container.

• High cardinality: many distinct values mean many small logical partitions that can be spread across physical partitions.
• Even request distribution: no value should receive far more reads or writes than the others, or one partition throttles while the rest sit idle.
• Even storage distribution: no value should approach the 20 GB logical partition limit.
• Used in filters: a query that includes the key stays in one partition. Without it, the query becomes a cross-partition query that fans out to every partition and costs more RUs.

The animated diagram below walks through these checks as a decision tree, from your top queries to a single-property key, a hierarchical key, or a data model rework.

Worked Example: Which Key Fits an IoT Workload?

Microsoft’s IoT partitioning example compares three options for a system ingesting data from more than 50K devices. Only the third passes every check.

When Should You Use Hierarchical Partition Keys?

Use Cosmos DB hierarchical partition keys when one property cannot satisfy the checks alone. They are generally available and allow up to three levels (e.g. TenantId, UserId, SessionId). They replace many synthetic-key designs, especially in multi-tenant workloads.

• Keep every level high cardinality: this applies from the first level onward.
• Watch the first level’s real traffic: a first level that looks high cardinality can still be hot if the workload touches only a few values.
• Order levels by filter use: put the level that appears most often in your filters first, in the order you filter on them.

Items that share the same first-level value sit on the same physical partition, so queries on that value avoid a full fan-out. If the key ends with a unique value such as /id, the earlier levels can grow past 20 GB. No account-level setting is needed.

The code below creates a container with a three-level key (TenantId, UserId, id) and reads one item by building the full key. Use a recent version of the Microsoft.Azure.Cosmos package from NuGet.

C#

using Microsoft.Azure.Cosmos;

CosmosClient client = new CosmosClient(endpoint, key);
Database database = client.GetDatabase("appdb");

ContainerProperties properties = new ContainerProperties(
    id: "sessions",
    partitionKeyPaths: new List<string> { "/TenantId", "/UserId", "/id" });

ContainerResponse created =
    await database.CreateContainerIfNotExistsAsync(properties, throughput: 400);
Container container = created.Container;

PartitionKey partitionKey = new PartitionKeyBuilder()
    .Add("tenant-42")
    .Add("user-1001")
    .Add("session-9")
    .Build();

ItemResponse<Session> response =
    await container.ReadItemAsync<Session>("session-9", partitionKey);

public record Session(string id, string TenantId, string UserId);

The PartitionKeyBuilder values follow the path order, and the last value matches the item’s id.

Warning: You cannot change the partition key of an existing container in place. To change it, create a new container with the right key and copy the data across, so decide early and test your key against real access patterns first.

Fix a Cosmos DB Hot Partition with a Better Data Model

A Cosmos DB hot partition is one partition that takes far more RU or storage than the others. It starts to throttle while the rest of the container sits idle.

In plain English: Picture a supermarket with ten checkout lanes where every customer joins lane one. Lane one has a long queue while nine cashiers wait. Adding more cashiers doesn’t help, because customers still pick the same lane.

How do you detect a hot partition?

Compare partition-level metrics with the container-wide numbers in Azure Monitor (Metrics). Look at normalized RU consumption split by partition.

• Skew pattern: a few partitions sit near 100% while the container average stays low. This points to a skewed key, not a lack of capacity.
• Matching symptom: 429 responses appear even though total consumption looks well below what you provisioned.

Why doesn’t raising RU/s fix it?

Provisioned throughput is divided across physical partitions, so the hot partition still gets only its own share. Extra RU/s mostly pays for capacity the idle partitions never use. That is why this is a data model problem first and a Cosmos DB cost optimization problem second.

A Cosmos DB Conf 2026 production lesson shows this. One logical partition took over 80% of traffic. After the data model was fixed, with no extra scaling, RU utilization fell to 20-35% and throttling stopped.

What should you change in the data model?

Change the key or the shape of the data, in this order of preference:

1. Pick a higher-cardinality key: choose a property with many distinct values that your workload actually touches evenly.
2. Use hierarchical partition keys: add levels such as TenantId, UserId, id so one large tenant spreads across many partitions.
3. Add a spreading level: a time bucket (e.g. day or month) stops current writes from landing on one value.
4. Split read and write shapes: when one key can’t serve both, use the design below.

Should you colocate entity types in one container?

Yes, colocate related entity types in one container, or a small number of containers. Queries are scoped to one container, and multi-item atomic transactions (stored procedures and triggers) are scoped to one partition key in one container. Colocation also cuts network round trips.

If you can’t colocate, for example when migrating an existing app unchanged, consider database-level shared throughput.

What is the write-optimized container with change feed design?

Write to one container whose key spreads writes evenly. Then feed other containers through the change feed, each keyed for one read pattern. The animated diagram below shows this flow.

Example: a retail orders container is partitioned for even writes. The change feed processor copies each order into one container keyed by CustomerId and another keyed by ProductId. Both read paths then run as single-partition queries.

Microsoft announced the All Versions and Deletes change feed mode as generally available at Build 2026. Confirm its status in the announcement before you rely on it.

Trade-off: read-model containers add storage cost and eventual lag, since copies arrive after the write. Use them only when one partition key cannot serve both access patterns.

Cosmos DB RU Optimization and 429 Throttling

To reduce Cosmos DB request units, use point reads instead of queries, keep queries inside one partition, project only the fields you need and trim the indexing policy. Each of these lowers the RU charge, and RU charge drives both cost and throttling.

How Do You Measure Cosmos DB RU Cost?

Read the RequestCharge from every response. The same query on the same data always costs the same RUs, so the number is repeatable and safe to compare before and after a change.

Query execution metrics show where the RUs went. Paged results are charged per page, and the pages add up to the cost of the whole query. Measure your own workload instead of copying generic savings figures.

In plain English: An RU is like a price tag on each operation. A cheap lookup costs a few coins, a big scan costs many, and your provisioned RU/s is the coins you get each second.

Point Read vs Query: Which Costs Less?

A point read is the cheapest way to fetch one item. The table compares the three access shapes.

Query cost depends on the number and kind of predicates, the number of UDFs and the size of the source data. A query returning a thousand 1-KB items costs about 1,000 RUs, so at 1,000 RU/s you get roughly one such query per second before throttling. Use SELECT c.id, c.name, c.price instead of SELECT *.

Use case: A retail catalog service serves product pages by id and category. With category as the partition key, the product page is a point read, and the category listing is a single-partition query.

How Do You Trim the Indexing Policy?

Exclude paths you never filter or sort on. Every indexed path is maintained on each write, so fewer paths mean fewer write RUs.

JSON

{
  "indexingMode": "consistent",
  "includedPaths": [ { "path": "/*" } ],
  "excludedPaths": [ { "path": "/descriptionHtml/*" } ]
}

This simplified policy indexes everything except a large, unused description field.

Which Throughput Mode Should You Use?

Throughput is set at container level or shared at database level, and you can change it at any time. You pay for what you configure, so match RU/s to the real workload shape. Verify current limits on the pricing page.

What Happens When Cosmos DB Returns 429?

When a request exceeds provisioned throughput, the service ends it with HTTP 429 (RequestRateTooLarge) and an x-ms-retry-after-ms header with the wait time in milliseconds. The SDK retry settings decide how many retries happen before the exception reaches your app.

The animated diagram below shows how a throttled request is retried, and what happens when retries run out.

Workloads that aren’t latency-sensitive can run with less throughput and rely on this rate limiting. If 429s come from one hot partition, fix the key. More RU/s is split across partitions and won’t help.

How Do You Log RU Charge and Handle 429 in .NET?

Check NuGet for the current Microsoft.Azure.Cosmos version before you start. First, set the retry options on the client:

C#

// Run this once at application startup, not per request.
var client = new CosmosClient(connectionString, new CosmosClientOptions
{
    MaxRetryAttemptsOnRateLimitedRequests = 5,
    MaxRetryWaitTimeOnRateLimitedRequests = TimeSpan.FromSeconds(10)
});
Container container = client.GetContainer("retail", "products");

The SDK stops retrying a throttled call once it has made 5 retries or waited 10 seconds in total, whichever comes first, and then throws.

Create one CosmosClient per application lifetime and reuse it. The client is designed to be shared and is thread-safe, so register it as a singleton (e.g. in your dependency injection container) and inject the Container where needed. Creating a new client for every request wastes connections and adds startup cost to each call. The snippet above shows the client only to demonstrate the options, and the later examples assume the same shared container.

The values 5 and 10 seconds are example settings, not the SDK defaults. The research notes don’t list the default values, so check the current Cosmos DB .NET SDK documentation for them. Raising the limits makes the SDK wait longer and hide more throttling from your app, and lowering them makes 429 exceptions reach your code sooner. Pick values that fit how long a caller can wait.

C#

public record Product(string id, string category, string name, decimal price);

ItemResponse<Product> response = await container.ReadItemAsync<Product>(
    "sku-1001", new PartitionKey("shoes"));
Console.WriteLine($"Point read RU: {response.RequestCharge}");

This point read logs its own RU charge.

C#

public record ProductSummary(string id, string name, decimal price);

var query = new QueryDefinition(
    "SELECT c.id, c.name, c.price FROM c WHERE c.category = @category")
    .WithParameter("@category", "shoes");
var options = new QueryRequestOptions { PartitionKey = new PartitionKey("shoes") };

double totalRu = 0;
using FeedIterator<ProductSummary> iterator =
    container.GetItemQueryIterator<ProductSummary>(query, requestOptions: options);
while (iterator.HasMoreResults)
{
    FeedResponse<ProductSummary> page = await iterator.ReadNextAsync();
    totalRu += page.RequestCharge;
}
Console.WriteLine($"Query RU: {totalRu}");

This single-partition query projects three fields and adds up the charge for every page.

C#

try
{
    await container.ReadItemAsync<Product>("sku-1001", new PartitionKey("shoes"));
}
catch (CosmosException ex) when (ex.StatusCode == System.Net.HttpStatusCode.TooManyRequests)
{
    Console.WriteLine($"Throttled. Retry after: {ex.RetryAfter}");
    Console.WriteLine(ex.Diagnostics.ToString());
    // Back off here before trying again.
}

This catch block runs only after the SDK has used up its retries, so log the diagnostics and back off.

Cosmos DB Consistency Levels: Choose and Override

Cosmos DB offers five consistency levels: Strong, Bounded Staleness, Session, Consistent Prefix and Eventual. Session is the default. Pick the weakest level your correctness rules allow for each read, because stronger levels cost more.

In plain English: Consistency is how quickly an update you save shows up for everyone else. Think of a news site: one screen shows the new headline, and consistency decides how long another screen may still show the old one. Unlike a news site, Cosmos DB lets you choose that wait.

What Does Each Consistency Level Guarantee?

The table below describes what a reader sees at each level and where it fits.

What Are the Trade-offs?

Stronger levels add latency and reduce availability. Strong is also not available when the account uses multi-region writes. Strong and Bounded Staleness reads cost more RUs than reads at the weaker levels, so a stricter default has a price on every read that does not override it.

The size of that difference depends on your data and access pattern. Measure RequestCharge for your own reads at each level instead of trusting a generic figure.

How Do You Override Consistency Per Request?

You can set the consistency level on a single request with ItemRequestOptions.ConsistencyLevel. The rule is simple: a per-request override can only be equal to or weaker than the account default, never stronger.

This means the account default is your ceiling. If the default is Session, you cannot raise a single request to Strong. To have any request read at Strong, the account default itself must be Strong.

So the design works in one direction. Set the account default to the strictest level your most sensitive reads need, then relax it per request for reads that can tolerate staleness. Here is a simplified example for a retail review feed:

C#

var options = new ItemRequestOptions
{
    ConsistencyLevel = ConsistencyLevel.Eventual
};

ItemResponse<Review> response = await container.ReadItemAsync<Review>(
    id: "review-1001",
    partitionKey: new PartitionKey("product-42"),
    requestOptions: options);

Console.WriteLine($"RU charge: {response.RequestCharge}");

This reads one review at Eventual consistency, which is weaker than any account default, and logs its RU charge so you can compare levels.

Example: A banking service sets the account default to Strong, because balance checks must always see the latest committed write (this needs an account without multi-region writes). Reads that tolerate delay, such as a statement history page, relax to Session or Eventual on each request to save latency and RUs. A retail product-review feed relaxes to Eventual the same way, since a review appearing a few seconds late harms nobody.

Common Anti-Patterns, Operations and Production Readiness Checklist

Most production incidents trace back to a few repeated design mistakes. The table below lists each one with the symptom you will see and the fix.

Which Cosmos DB anti-patterns cause the most trouble?

In plain English: A cross-partition query is like asking every room in a library to search its shelves for you. A good key sends you to the one room that holds your book.

What should you monitor in production?

Watch three signals: normalized RU consumption, 429 counts and provisioned RU/s.

• Normalized RU consumption: check it per partition, not only as a container average, to spot skew.
• 429 counts: a steady stream means a hot partition or too little throughput.
• Provisioned RU/s: match it to the real shape of your workload. This is the main lever for Cosmos DB cost optimization.

How do you migrate to a new partition key?

You can’t change the partition key of an existing container in place. Create a new container with the right key, copy the data (e.g. with change feed or a bulk copy job) and cut over. Test the whole process on a copy first.

Which recent features need a status check?

Build 2026 (June 2026) announced the Linux Emulator and the All Versions and Deletes change feed mode as generally available, along with Global Secondary Indexes. Verify each feature’s status in the announcement before you depend on it.

Production readiness checklist

Work through these steps in order before go-live:

1. Model access patterns: list your reads, writes and filters first.
2. Choose and load-test the partition key: use realistic data and traffic.
3. Confirm 20 GB headroom: check that no logical partition value can outgrow the limit.
4. Colocate entities: group related types in one container where queries and transactions need it.
5. Trim the indexing policy: exclude unused paths.
6. Log RequestCharge: record it for every operation.
7. Use a singleton CosmosClient: create one client per application and reuse it for all requests, instead of creating a new client per call. The client holds the connections and the retry settings, so sharing it keeps behavior consistent.
8. Set SDK retry options: configure the retry count and maximum wait on that single client.
9. Consider preferred regions and direct mode (optional): if your account has more than one region, set the preferred regions list so the SDK reads from the closest one. Also review the SDK’s connection mode (direct or gateway) for your workload. Check the current SDK documentation for the exact options.
10. Alert on 429s and partition skew: watch both.
11. Relax consistency per request where staleness is acceptable: set the account default to the weakest level your correctness rules allow. Then relax individual reads that tolerate stale data, for example a product-review feed. A request can only use a level equal to or weaker than the default, so confirm this rule on the official consistency-levels page.
12. Rehearse migration and restore: prove you can recover before you must.

Key takeaways

These are the points to remember from this guide, in the order you will likely need them when designing or fixing a Cosmos DB workload:

• Choose the partition key from access patterns: pick a key with high cardinality that spreads both storage and RU use evenly and appears in your most common query filters. Keep each logical partition well under the 20 GB limit.
• Use hierarchical partition keys for multi-tenant workloads: you can use up to three levels (e.g. TenantId, UserId, id), and every level should have high cardinality. Ending the key with a unique value such as /id lets the earlier levels grow past 20 GB.
• Fix hot partitions with the data model, not more RU/s: throughput is divided across physical partitions, so raising it does not help a skewed key. Change the key, add a spreading level, or split read and write shapes with change feed.
• Prefer point reads and project only what you need: read by id plus partition key when you can, keep queries inside one partition, and select specific properties instead of SELECT *. Exclude paths you never filter or sort on from the indexing policy to lower write cost.
• Measure RequestCharge and handle 429s deliberately: log the RU charge for each important operation, set the SDK retry options, and alert on throttling and partition skew. A 429 caused by a hot partition needs a key fix, not a bigger RU/s setting.
• Treat the account default consistency as the ceiling: Session is the default, so pick the weakest level your correctness rules allow. A request can only relax that level, never make it stronger. If a critical read (e.g. a banking balance check) needs stronger guarantees, set the account default to that stronger level and relax it per request for the reads that can tolerate it. Confirm these rules on the official consistency-levels page.
• Decide the partition key early: you cannot change it in place on an existing container. A change means creating a new container, copying the data and cutting over, so rehearse that migration on a copy first.

That’s all! Happy coding!

Did this guide solve your Cosmos DB partitioning, RU or consistency issue? Please share your questions or experience in the comments below.

Bookmark this page or share it with your team, so it is handy for your next design review. Subscribe to TheCodeBuzz for more database best-practice guides.

FAQ

How do I choose a good partition key in Cosmos DB?

Choose a key with high cardinality that spreads both storage and RU use evenly and appears in your most common query filters. Keep each logical partition well under the 20 GB limit, and avoid keys that send all current writes to one value, such as a purely time-based key. If you need more than one level, a hierarchical key of up to three levels (e.g. TenantId, UserId, id) works well for multi-tenant workloads. Decide early, because the key of an existing container cannot be changed in place.

What is a hot partition in Cosmos DB and how do I fix it?

A hot partition is one partition that takes far more RU or storage than the others, so it throttles while the rest of the container sits idle. To detect it, compare normalized RU consumption per partition in Azure Monitor. A few partitions near 100% while the container average stays low points to skew. Fix it with the data model: pick a higher-cardinality or hierarchical key, add a spreading level such as a time bucket, or split read and write shapes. Raising RU/s does not help, because throughput is divided across partitions.

How do I reduce RU consumption in Cosmos DB?

Use point reads by id and partition key instead of queries, keep queries inside a single partition, and select only the properties you need instead of SELECT *. Exclude paths you never filter or sort on from the indexing policy, since every indexed path is maintained on each write. Then measure the RequestCharge of each operation, because the same query on the same data always costs the same RUs. Check your own workload rather than relying on generic savings figures.

How do I fix 429 Request Rate Too Large errors in Cosmos DB?

First check whether the 429s come from a hot partition. If they do, fix the partition key or data model, because adding RU/s will not solve skew. If load is spread evenly, tune the SDK retry settings (MaxRetryAttemptsOnRateLimitedRequests and MaxRetryWaitTimeOnRateLimitedRequests), which honor the x-ms-retry-after-ms header the server returns. If throttling stays steady after that, raise throughput to match the real workload shape. Workloads that are not latency-sensitive can run with less throughput and rely on rate limiting.

Which Cosmos DB consistency level should I use, and what is the default?

Session is the default level, but it is not the right choice for every workload. Pick the weakest level your correctness rules allow, since stronger levels cost more in latency and availability.

The account default is the strongest level any request can get. A request can only weaken it with a per-request override, never strengthen it. So if even one operation, such as a banking balance check, needs a strong guarantee, the account default must be at least that strong. Then relax the other, less critical reads (e.g. a product-review feed) per request.

Confirm on the official consistency-levels page whether Strong is available with multi-region writes, because that detail comes from a third-party source.

Sources and further reading

• Hierarchical Partition Keys – Azure Cosmos DB (Microsoft Learn)
• Unlimited logical partition storage with hierarchical partition keys – Azure Cosmos DB (Microsoft Learn)
• Optimize Request Cost – Azure Cosmos DB (Microsoft Learn)

The post Cosmos DB Best Practices: Partitioning, RU and Consistency first appeared on TheCodeBuzz.

The scope is modeling, supernodes, indexes and constraints, reading plans with EXPLAIN and PROFILE, batched writes, Cypher 25 vs Cypher 5, operations, common anti-patterns and a production readiness checklist. The model is query-driven. You write down your important queries first and let them shape the graph. A graph isn’t always the right choice, and we will say when a relational database is simpler.

Neo4j ships roughly monthly in calendar-versioned releases, and the 5.26 LTS line is still patched. Many older guides ignore Cypher 25, the default language setting and concurrent batching, so this one covers them. Check the deployment center for the latest patch before you install.

Version note: This guide targets Neo4j 2026.10.2 and Neo4j 5.26 LTS (5.26.33), both released on 6 November 2026, with Cypher 25 and Cypher 5.

In this guide

• Neo4j Best Practices at a Glance
• Neo4j Graph Data Modeling: Nodes, Relationships, Properties and Supernodes
• Neo4j Indexes, Constraints and Cypher Query Optimization with EXPLAIN and PROFILE
• Batching Writes and Choosing Between Cypher 25 and Cypher 5
• Neo4j Performance Tuning and Operations: Memory, Monitoring, Backups and Upgrades
• Common Anti-Patterns and Production Readiness Checklist
• Key takeaways
• FAQ

Neo4j Best Practices at a Glance

Neo4j is a graph database that stores data as nodes and relationships and is queried with Cypher. This guide covers Neo4j graph data modeling, Cypher query optimization, Neo4j performance tuning and operations, so you can run it safely in production.

Note: Think of a subway map versus a spreadsheet. A spreadsheet lists stations in rows, and finding a route means matching rows again and again. A subway map stores the connections directly, so you just follow the lines. A graph database works like the map: the links between things are stored, not worked out at query time.

Best practices summary table

The table below shows what to do and what to avoid in each area. Later sections explain the reasoning.

Which Neo4j versions are current?

Neo4j 2026.10.2 and 5.26.33 are the current builds, both released on 6 November 2026. Check the deployment center for the latest patch before you install.

Neo4j Graph Data Modeling: Nodes, Relationships, Properties and Supernodes

Write your most important queries first, let them decide what becomes a node, a relationship or a property, and then test the model on a loaded sample of real data. Neo4j’s own modeling guidance says there is no single right model, and the model can change as your priorities change. Good Neo4j graph data modeling is therefore iterative, not a one-time design.

Note: In a graph, a relationship is stored as a direct link between two nodes. Think of a subway map: you follow the lines from station to station. A spreadsheet is more like a timetable, where you search rows to find a match. The analogy stops fitting when a station has thousands of lines, which is the supernode problem covered below.

How do I decide between a node, a relationship and a property?

Use the questions in the table below. The animated diagram that follows walks through the same decisions step by step.

Keep the label count sensible. Add a new label when queries really need to tell the entities apart, not for every small variation.

When should a relationship become an intermediate node?

Use an intermediate node when the connection has rich data, joins more than two things, or must itself be connected or indexed. Example: in retail, a Purchase node can link a Customer, a Product and a Store, and carry the price, quantity and timestamp. A single relationship cannot join three entities.

How do I model date-range queries?

If queries must return results within a date range, consider a separate date node or relationship instead of a node property. The query then traverses to a small set of date nodes and follows their links, instead of testing a date property on a large number of candidate nodes.

How do I avoid supernodes?

A supernode is a dense node with a very large number of relationships. Traversing it is slow because the expansion has to touch every relationship it holds. Use these patterns:

• Split by relationship type: use distinct types instead of one type for everything.
• Bucket by time: Account -> Month -> Transaction.
• Add category nodes: put an intermediate node between the hub and its many neighbors.
• Filter on type and direction: name both in the pattern so the query ignores relationships it doesn’t need.

Example: a finance Account with millions of transactions is remodeled so each transaction hangs off a monthly bucket node. With one bucket per month, an account open for three years would hold about 36 HAS_MONTH relationships (an illustrative figure, your numbers will differ), and each month holds only its own transactions.

Which constraints does the bucketed model need?

Create the constraints before loading data, so every MERGE and MATCH in the model starts with an index seek and not a label scan. Each constraint creates a backing index on its key. Run these statements once, as separate commands:

Cypher

CREATE CONSTRAINT account_id_unique IF NOT EXISTS
FOR (a:Account) REQUIRE a.accountId IS UNIQUE;

CREATE CONSTRAINT month_key_unique IF NOT EXISTS
FOR (m:Month) REQUIRE (m.accountId, m.month) IS UNIQUE;

CREATE CONSTRAINT transaction_id_unique IF NOT EXISTS
FOR (t:Transaction) REQUIRE t.txId IS UNIQUE;

The composite constraint on Month makes the pair accountId and month the lookup key. A node key constraint on the same two properties also works if your edition supports it.

How do I create and query the monthly buckets?

Merge each node on its constrained key, then connect them, so a repeated load does not create duplicates. The query side starts at one account, so it is anchored on an indexed property.

Cypher

// Create: account, monthly bucket and transaction
MERGE (a:Account {accountId: $accountId})
MERGE (m:Month {accountId: $accountId, month: $month})
MERGE (a)-[:HAS_MONTH]->(m)
CREATE (m)-[:CONTAINS]->(:Transaction {txId: $txId, amount: $amount, postedAt: datetime($postedAt)});

// Query: one month of transactions for one account
MATCH (:Account {accountId: $accountId})-[:HAS_MONTH]->(:Month {month: $month})-[:CONTAINS]->(t:Transaction)
RETURN t.txId, t.amount, t.postedAt
ORDER BY t.postedAt;

The query finds one account through its constraint index, jumps to one month and reads only that month’s transactions. Run PROFILE on it with sample data to confirm the plan shows index seeks and no NodeByLabelScan.

When is a graph the wrong choice?

Use a relational database when the work is mostly aggregations over flat tables, bulk analytics scans, or data with few relationships. A graph pays off when queries follow connections, and it adds modeling effort that flat data does not repay.

Neo4j Indexes, Constraints and Cypher Query Optimization with EXPLAIN and PROFILE

The fastest Cypher queries start at specific nodes found through an index or constraint. Anchor every query on an indexed property, then check the plan with EXPLAIN (shows the plan, executes nothing) and PROFILE (runs the query and shows rows and db hits).

Note: An index works like the index at the back of a book: you look up a word and jump to the right page. A label scan is reading every page to find it. The analogy stops at writes, because Neo4j also has to update the index whenever data changes.

Which constraints and indexes should you create?

Create a uniqueness constraint on the natural key (e.g. a customer email or order number). It also creates the backing index, so lookups on that key become index seeks. Add range or text indexes for properties you filter on often.

Cypher

CREATE CONSTRAINT customer_email_unique IF NOT EXISTS
FOR (c:Customer) REQUIRE c.email IS UNIQUE;

CREATE INDEX order_date_range IF NOT EXISTS
FOR (o:Order) ON (o.orderDate);

CREATE TEXT INDEX product_name_text IF NOT EXISTS
FOR (p:Product) ON (p.name);

The first statement enforces uniqueness, the second speeds up date filters, and the third supports string matching on product names.

The constraint matters most for MERGE, which means “match this pattern or create it”. Without a constraint, MERGE may scan the label, and two concurrent transactions can both find nothing and both create the node. With the constraint, the lookup is an index seek and duplicates are rejected. The 2025 changelog added the MergeUniqueNode and MergeInto operators, so MERGE on a constrained key is cheaper than it used to be.

Cypher

MERGE (c:Customer {email: $email})
ON CREATE SET c.name = $name, c.createdAt = datetime()
ON MATCH SET c.lastSeen = datetime()
RETURN c.email;

The email and name come in as parameters, and the constrained key keeps the merge safe and fast.

How do you read a PROFILE plan?

Read the plan from the bottom up and look at the leaf operators first. Db hits are the units of storage work an operator does. Cardinality is the number of rows an operator produces (estimated in EXPLAIN, actual in PROFILE).

The animated diagram below shows the tuning loop: run EXPLAIN, run PROFILE, match the warning sign to a fix, and repeat until the plan shows an index seek.

This table lists the operators you will see most often and what to do about each one:

A large gap between estimated and actual rows is another warning, because the planner chose its plan on wrong numbers. PROFILE uses extra resources, so use it while tuning, not as a habit on every production query.

Here is a retail example. Before the constraint exists, the lookup is a label scan:

Cypher

PROFILE
MATCH (c:Customer {email: $email})-[:PLACED]->(o:Order)
RETURN o.orderId, o.total;

// Before: NodeByLabelScan on Customer, then Filter on email
// Fix:
CREATE CONSTRAINT customer_email_unique IF NOT EXISTS
FOR (c:Customer) REQUIRE c.email IS UNIQUE;
// After: NodeUniqueIndexSeek on Customer, far fewer db hits

The leaf operator changed from NodeByLabelScan to NodeUniqueIndexSeek, so the query touches one customer instead of all of them.

Which query rules improve Cypher performance?

These rules cover most Cypher query optimization work, and each one has a reason:

• Use parameters: Neo4j can auto-parameterize some simple literals, but that does not cover every query. Explicit parameters are the reliable way to get plan reuse, because the cached plan is shared across all values.
• Filter early: Fewer rows early means less work in every later operator.
• Aggregate early: Collapse rows before further matching or joining.
• Return properties: RETURN o.orderId, o.total moves less data than returning whole nodes.
• Cap variable-length paths: Write [:KNOWS*1..4], because an unbounded path can explore most of the graph.
• Be explicit: Give labels and relationship types, including on both ends of a relationship, so the planner has better statistics.
• Avoid Cartesian products: Two disconnected MATCH patterns multiply their rows. Connect them or split the query.
• Limit OPTIONAL MATCH chains: Each one keeps rows alive that a plain MATCH would drop.

How do you run a parameterized query from Python?

Pass values as keyword arguments to execute_query and never build the query string by hand. This keeps plans reusable and blocks Cypher injection.

Python

from neo4j import GraphDatabase, RoutingControl

URI = "neo4j://localhost:7687"
AUTH = ("shop_app", "change-me")

with GraphDatabase.driver(URI, auth=AUTH) as driver:
    records, summary, keys = driver.execute_query(
        "MATCH (c:Customer {email: $email})-[:PLACED]->(o:Order) "
        "RETURN o.orderId AS orderId, o.total AS total",
        email="anita@example.com",
        database_="neo4j",
        routing_=RoutingControl.READ,
    )
    for record in records:
        print(record["orderId"], record["total"])

The email value travels as a parameter, and routing_=RoutingControl.READ sends the read to a suitable cluster member. The shop_app user is a placeholder account name, so assign it a least-privilege role such as the read-only role described in the security section.

Batching Writes and Choosing Between Cypher 25 and Cypher 5

Load data with CALL { } IN TRANSACTIONS instead of one huge transaction. Memory stays bounded and a failure only affects one batch. A transaction batch is a fixed number of input rows that are committed together as one small transaction.

How do you load data in batches?

Create the uniqueness constraint first, then read the rows and commit every 10,000 of them in their own transaction. MERGE on a constrained key means a re-run does not create duplicates, and the constraint is what enforces that.

Note: Think of moving house. One trip with every box will overload the van, but many trips with a few boxes each are safe, and a flat tyre only costs you one trip. Unlike boxes, a committed batch stays in the database even if a later batch fails.

This statement creates the constraint on the lookup key. Run it once, before the load, as its own statement:

Cypher

CREATE CONSTRAINT order_id_unique IF NOT EXISTS
FOR (o:Order) REQUIRE o.orderId IS UNIQUE;

The constraint also creates a backing index, so each MERGE looks up the order by orderId instead of scanning the Order label. IF NOT EXISTS makes the statement safe to repeat in deployment scripts.

This statement loads the orders in batches of 10,000 rows:

Cypher

LOAD CSV WITH HEADERS FROM 'file:///orders.csv' AS row
CALL (row) {
  MERGE (o:Order {orderId: row.orderId})
  SET o.total = toFloat(row.total)
} IN TRANSACTIONS OF 10000 ROWS;

The same pattern works with UNWIND $rows AS row for a parameter list. This statement must run in an implicit (auto-commit) transaction, so in Neo4j Browser prefix it with :auto and do not wrap it in BEGIN.

Can you run batches concurrently?

IN CONCURRENT TRANSACTIONS runs several batches in parallel and speeds up large loads. It can also deadlock when two batches try to lock the same node, for example two orders for the same customer.

The animated diagram below shows batches entering three lanes, a deadlock risk appearing, and DISJOINT BY routing the conflicting batches into separate lanes.

Cypher 25 adds DISJOINT BY to schedule batches so conflicting ones do not run together. The 2026 changelog marks it experimental, so test it on your own data before using it in production. Check the Cypher Manual for your exact server version for the current syntax, because experimental features can change.

A database-wide default batch strategy can be set with dbms.cypher.transactions.default_subquery_batch_strategy.

Cypher 25 vs Cypher 5: which should you use?

Use Cypher 25 for new work unless you depend on Cypher 5 features that it removed. The table compares the two languages.

How do you set the Cypher version?

Set a default per database, and override it per query with a version prefix. This lets you migrate one database or one query at a time.

Cypher

ALTER DATABASE sales SET DEFAULT LANGUAGE CYPHER 25;

CYPHER 5
MATCH (c:Customer {customerId: $id}) RETURN c.name;

CYPHER 25
MATCH (c:Customer {customerId: $id}) RETURN c.name;

The first statement changes the default for the sales database. The prefixed queries run in the named version regardless of that default.

Warning: Since 2026.02 the neo4j.conf shipped with the server sets db.query.default_language=CYPHER_25. If you reuse a config file across upgrades or new servers, check this setting, because it decides which language new databases default to.

Neo4j Performance Tuning and Operations: Memory, Monitoring, Backups and Upgrades

Size the page cache and heap separately, log slow queries, back up and rehearse restores, and treat every upgrade as a tested change. The monthly releases have shipped regressions, so none of this is optional for production.

How should you size memory and storage?

Neo4j uses two memory areas for different jobs. The page cache holds graph data and indexes, and the heap holds query execution state.

Note: Think of the page cache as a bookshelf next to your desk that keeps the books you read most often. The heap is the scratch paper for the question you are answering right now. A bigger bookshelf won’t help if your scratch paper keeps overflowing.

A larger page cache does not fix a query that builds huge intermediate results, because that pressure lands on the heap. Fix the query first (see the PROFILE guidance earlier in this article). Run the neo4j-admin server memory-recommendation command for a starting estimate, then adjust from monitoring data. Keep data files and transaction logs on fast SSD storage.

What should you monitor?

Turn on query logging first, so slow queries are recorded instead of guessed at. Here is a simple example for neo4j.conf that logs only queries slower than one second:

neo4j.conf

db.logs.query.enabled=INFO
db.logs.query.threshold=1s

At the INFO level, the threshold decides which queries are written to the log, so only queries that run longer than one second appear. Do not use VERBOSE for this purpose. It logs the start and end of every query and the threshold only applies at INFO, so the log grows quickly and the one-second filter has no effect.

Beyond the query log, track these:

• Page cache hit ratio: a falling ratio means the working set no longer fits in memory.
• Heap and GC: long or frequent garbage collection pauses point to queries holding too much state.
• Transaction counts: watch open, committed and rolled-back transactions for spikes.

Run PROFILE only on the worst offenders from the log, since it adds overhead.

How do you secure a Neo4j deployment?

Give the application a least-privilege user through role-based access control, and encrypt traffic with TLS for both Bolt and HTTP. Always pass values as parameters, which also prevents Cypher injection. The example below creates a read-only role for a reporting service:

Cypher

CREATE ROLE app_reader IF NOT EXISTS;
GRANT ACCESS ON DATABASE neo4j TO app_reader;
GRANT MATCH {*} ON GRAPH neo4j TO app_reader;
CREATE USER report_svc IF NOT EXISTS SET PASSWORD $password CHANGE NOT REQUIRED;
GRANT ROLE app_reader TO report_svc;

The service can now read the graph but cannot write or change the schema.

How do you back up and restore safely?

Take regular full and differential backups, then restore them into a separate environment on a schedule. A backup you have never restored is unproven. This command lets Neo4j choose between a full and a differential backup:

Shell

neo4j-admin database backup --from=db-host:6362 --type=AUTO --to-path=/backups/neo4j neo4j

If you use Ops Manager, version 1.15 and later (1.15.6 is current) needs a persistence database on Neo4j 5.26 LTS or newer.

What does clustering give you?

A cluster gives you availability and read scaling. Reads can be served by several members, while writes for a database go to its leader, which is one of the primary members for that database. A cluster does not replace backups.

How should you handle upgrades?

Pin to exact patch versions and test every upgrade in staging. The release notes record that 2026.07.0 could fail unexpectedly when using trim(), and 2026.08.0 could make some queries fail. Patch releases fixed both.

For clusters, read the upgrade notes first, then do a rolling upgrade one member at a time. Current builds are 5.26.33 and 2026.10.2, both released 6 November 2026. The table compares the two tracks:

Common Anti-Patterns and Production Readiness Checklist

Most Neo4j problems in production trace back to a short list of repeated mistakes. The table below shows each one, how it appears, and how to fix it.

Which Neo4j anti-patterns cause the most trouble?

Note: A Cartesian product pairs every row from one list with every row from another, like matching each shirt with each pair of trousers. Two lists of 1,000 rows give 1,000,000 combinations.

What should you verify before going live?

Work through these steps in order and sign off each one.

1. Validate the model: run your top queries against a loaded sample of real data.
2. Verify indexes and constraints: create them, then confirm with PROFILE.
3. Use parameters: no literals in application queries.
4. Cap variable-length paths: every * pattern gets an upper bound.
5. Batch imports: no single huge write transaction.
6. Set the Cypher version: choose it per database.
7. Size memory and log queries: page cache and heap sized separately, query logging on.
8. Test restores: schedule backups and rehearse a restore elsewhere.
9. Review security: role-based access control and TLS.
10. Pin and rehearse upgrades: lock to a patch release and run the upgrade in staging first.

This snippet lists existing indexes and constraints so you can confirm steps 1 and 2:

Cypher

SHOW INDEXES YIELD name, type, labelsOrTypes, properties, state;
SHOW CONSTRAINTS YIELD name, type, labelsOrTypes, properties;

Every index should show ONLINE as its state, and each MERGE key should appear in the constraints list.

Key takeaways

• Queries drive the model: Write your most important queries first, load a sample of real data, and test the model against them before committing. The model can change when priorities change.
• Use specific relationship types and intermediate nodes: Name relationships after the verb (e.g. PLACED, CONTAINS) instead of a generic CONNECTED_TO. When a connection carries rich data or links more than two things, make it a node.
• Split supernodes by type or time: Bucket by month (Account to Month to Transaction), add category nodes, and always filter on a specific relationship type and direction.
• Combine a constraint, parameters and MERGE: Create a uniqueness constraint on the lookup key, pass values as parameters, and MERGE on that key. This gives you an index-backed lookup, plan reuse and safe upserts.
• Read PROFILE for the warning signs: Look for NodeByLabelScan on large labels, CartesianProduct, Eager and a big gap between estimated and actual rows. Cap variable-length paths and return only the properties you need.
• Batch writes and treat DISJOINT BY as experimental: Use CALL { } IN TRANSACTIONS so memory stays bounded and failures stay small. Test DISJOINT BY thoroughly before relying on it in production.
• Choose the Cypher version deliberately: Set the default language per database and check your neo4j.conf, because the shipped file has defaulted to Cypher 25 since 2026.02. Use Cypher 25 for new work and migrate gradually.
• Pin patch releases and test restores: Monthly releases have shipped regressions (2026.07.0 and 2026.08.0), so rehearse upgrades in staging. A backup that has never been restored is unproven.

That’s all! Happy coding!

Did this article solve your Neo4j modeling or Cypher performance problem? Please share your questions and experience in the comments below.

Bookmark this guide or share it with your team, and subscribe to TheCodeBuzz for more database best-practices articles.

FAQ

How should I model data in Neo4j: node, relationship or property?

Use a node for an entity you look up or connect to, a relationship for a verb with a specific type (e.g. PLACED, CONTAINS), and a property for a value you only read after you reach the node. The exception is a connection that carries rich data, links more than two things, or must be indexed or connected itself. In that case, use an intermediate node, such as a Purchase node linking Customer, Product and Store. Write your important queries first and test the model on a loaded sample of real data.

How do I speed up a slow Cypher query?

Start by checking that the query is anchored on an indexed or constrained property, then work through the rest of this list:

• Parameters: Use them instead of literals so plans can be reused.
• Early filtering: Filter and aggregate as early as possible.
• Return only properties: Return the properties you need, not whole nodes.
• Capped paths: Put an upper bound on variable-length patterns, e.g. [:KNOWS*1..4].
• PROFILE: Run it to see which operator is doing the most work.

What do EXPLAIN and PROFILE show, and which operators should I look for?

EXPLAIN shows the query plan without running the query, so nothing executes. PROFILE runs the query and adds the actual rows and db hits for each operator. Node index seek and node index scan are the operators you want, because they start the query at specific nodes. Treat NodeByLabelScan on a large label, CartesianProduct, Eager and a big gap between estimated and actual rows as warning signs. Use PROFILE only while tuning, since it uses extra resources.

How do I avoid supernodes (dense nodes) in Neo4j?

Change the model so no single node collects millions of relationships. Split relationships by type, bucket them by time (e.g. Account to Month to Transaction), or add intermediate category nodes. In queries, filter on a specific relationship type and direction so the expansion does not touch every edge. A supernode is slow to traverse because the expansion has to go through all of its relationships.

What is the difference between Cypher 5 and Cypher 25, and which should I use?

Cypher 5 is frozen and receives only bug fixes and possible performance work. Cypher 25 started as a clone of Cypher 5 and gains features with each server release, but it has allowed only additive changes since it first appeared in server release 2025.06. Use Cypher 25 for new work unless you depend on Cypher 5 features that it removed, and migrate gradually. You can set the default per database with ALTER DATABASE <name> SET DEFAULT LANGUAGE CYPHER 25 and override it per query with a version prefix.

Sources and further reading

• Neo4j deployment center (Neo4j)
• Cypher versioning (Neo4j)
• Changes in Neo4j 2025-2026 series – Operations Manual (Neo4j)

The post Neo4j Best Practices: Graph Modeling and Cypher Performance first appeared on TheCodeBuzz.

Amazon DynamoDB is a managed key-value and document database. It has no versions and no maintenance windows, so new features ship continuously, and the notes in this guide reflect AWS announcements up to October 2026. The approach is access-pattern-first: you list how the application reads and writes data, then shape the keys and indexes around that list. Single-table design is explained as a tool for the right cases, not a universal rule.

Before we start, please check the prerequisites: basic familiarity with tables, items, partition key and sort key, plus an AWS account and a current SDK (boto3 for Python or the AWS SDK for .NET).

Version note: This guide targets the current DynamoDB service as of October 2026, including vector search (generally available Aug 5, 2026), global tables with multi-Region strong consistency (15 AWS Regions as of the Sept 2026 expansion) and the Streams AT_TIMESTAMP shard iterator (announced Oct 15, 2026).

In this guide

• DynamoDB Best Practices at a Glance
• DynamoDB Data Modeling: Access Patterns and Single-Table Design
• Partition Key, Sort Key and GSI Design: Avoid Hot Partitions
• Transactions, Consistency, Replication and Streams
• DynamoDB Cost Optimization: On-Demand vs Provisioned and Item Size
• DynamoDB Security, Backups, Monitoring, Anti-Patterns and Production Checklist
• Key takeaways
• FAQ

DynamoDB Best Practices at a Glance

Today in this guide, we will see how to design, run and pay for Amazon DynamoDB in production. DynamoDB is a fully managed NoSQL key-value and document database from AWS. We will cover data modeling, key design, indexes, transactions, replication, cost, security, backups and monitoring.

Version note: DynamoDB has no versions or maintenance windows, because features ship continuously. This guide is current to the Oct 2026 announcements.

In plain English: A partition is a physical storage unit that serves a slice of your table’s keys. Think of one checkout counter among many in a supermarket: each counter handles only some customers, and one counter can only serve so many people at a time.

The table below shows the main rules for each area. Later sections explain the reasoning behind each one.

DynamoDB Data Modeling: Access Patterns and Single-Table Design

For DynamoDB data modeling, list your access patterns first (e.g. “get customer by ID”, “list a customer’s orders newest first”) and shape the table to serve them. DynamoDB has no joins, so the table layout has to answer each question with a single key lookup or Query.

What Is Single-Table Design?

DynamoDB single table design means you denormalize and pre-join data at write time. Related items share a partition key, so one Query returns them together. The table shape follows how the data is read, not how it is normalized.

Note : A single-table layout is like filing a customer’s invoice, address and receipts in one folder. You pull one folder instead of visiting three cabinets. The analogy stops fitting when the folder grows very large, because one key has throughput limits (covered in the next section).

Which Key Conventions Should You Follow?

Use generic PK and SK attribute names, prefix values with the entity type (e.g. USER#, ORDER#), and add an entityType attribute. The attribute helps when debugging and lets stream consumers route each item to the right handler.

The table below shows a small item collection for a retail customer and orders. One Query on PK = USER#1001 returns the profile and all orders. Adding begins_with(SK, "ORDER#") returns only the orders.

How Do You Model Relationships?

Model one-to-many with a shared PK and SK prefixes, as in the table above. Model many-to-many with the adjacency list pattern, where each relationship is its own item.

• Education example: store PK = STUDENT#7, SK = COURSE#MATH101 and the mirror item PK = COURSE#MATH101, SK = STUDENT#7. A Query on either side lists the other.
• Retail example: do the same for products and categories. A GSI that swaps the keys can also serve the reverse lookup.

When Should You Not Use a Single Table?

Avoid a single table when entities scale or fail independently, need separate IAM, backup or blast radius, or have simple or still-changing access patterns. It pays off when patterns are known, related and high volume. The animated diagram below walks through this decision step by step.

The table compares the two approaches across the main concerns.

How Do Vector Search and Large Blobs Affect Modeling?

Native vector search became generally available on Aug 5, 2026. Embeddings sit next to your other attributes, and a vector index type works alongside GSIs and LSIs. For many RAG and semantic-search cases, this removes the need for a second database. AWS claims single-digit millisecond latency at 99%+ recall, so verify that against your own data.

Keep large blobs (images, PDFs, long documents) in S3 and store only the reference in the item. Item size drives read and write units, so a lean item is cheaper to read and write. The cost section explains the arithmetic.

Partition Key, Sort Key and GSI Design: Avoid Hot Partitions

Choose a high-cardinality partition key (many distinct values) whose traffic spreads evenly, and use the sort key for ordering and range queries inside one item collection. AWS advises designing for uniform activity across all partition keys in the table and in its secondary indexes.

What are the per-partition limits in DynamoDB?

Each partition is designed to deliver up to 3,000 read units and 1,000 write units per second. Item size counts toward these limits.

• Read unit: one strongly consistent read per second, or two eventually consistent reads per second, for an item up to 4 KB.
• Write unit: one write per second for an item up to 1 KB.

Example: a 20 KB item costs 5 read units per strongly consistent read (20 / 4). About 600 reads per second on that single item uses 3,000 read units, which is the partition limit.

What does adaptive capacity fix, and what does it not?

Adaptive capacity works in both on-demand and provisioned modes and helps when traffic is uneven across keys. It cannot raise the hard per-partition limit for one hot key. Total throughput is still bounded by your provisioned throughput or the on-demand table limit.

In plain English: A hot partition is one checkout lane with a huge queue while the other lanes sit empty. Adding more lanes does not help if every customer insists on the same lane.

Which partition keys work and which fail?

The table below compares common choices for DynamoDB partition key design.

How do you design the sort key?

The sort key orders items inside one partition key and enables range queries. Use ISO 8601 timestamps or prefixed values such as ORDER#2026-10-25, because they sort correctly as strings. Sort keys compare as plain strings, so a longer value sorts after its shorter prefix.

• begins_with: fetch all items for one prefix, e.g. ORDER#2026-10 for a month.
• between: fetch a date range. Both bounds are inclusive, so choose the upper bound with care (see the pitfall below).
• Composite sort keys: encode hierarchies such as COUNTRY#IN#CITY#PUNE to query at any level.

Here is the pitfall. Suppose your sort keys look like ORDER#2026-10-25#A18 (date, then order ID). The condition BETWEEN 'ORDER#2026-10-01' AND 'ORDER#2026-10-25' silently drops every order placed on the 25th, because ORDER#2026-10-25#A18 is longer than the upper bound and sorts after it. The lower bound is safe, since a shorter prefix sorts before the longer keys that start with it.

There are two simple fixes. Use the next day as the upper bound (ORDER#2026-10-26), or add a high character such as ~ to the end of the day (ORDER#2026-10-25~). The ~ character sorts after #, digits and letters in byte order, so it works when order IDs are plain alphanumeric text.

Python

import boto3
from boto3.dynamodb.conditions import Key

table = boto3.resource("dynamodb").Table("Orders")

resp = table.query(
    KeyConditionExpression=Key("PK").eq("USER#u-1001")
    & Key("SK").between("ORDER#2026-10-01", "ORDER#2026-10-25~")
)
orders = resp["Items"]

This returns all orders from 1 October to 25 October 2026 for one customer, including those placed on the 25th.

How does write sharding spread a hot key?

Write sharding appends a calculated or random suffix (e.g. a hash of orderId modulo N) to one logical key. The trade-off is that reads become scatter-gather: you query all N shards and merge. The animated diagram below shows the write fan-out and the read path.

The simplified example below writes with a stable hash suffix and reads the newest orders from four shards. Python’s built-in hash() changes between processes, so use hashlib.

Python

import hashlib
import boto3
from boto3.dynamodb.conditions import Key

SHARDS = 4
table = boto3.resource("dynamodb").Table("Orders")

def shard_for(order_id: str) -> int:
    return int(hashlib.md5(order_id.encode()).hexdigest(), 16) % SHARDS

def put_order(tenant, order_id, created_at, attrs):
    table.put_item(Item={
        "PK": f"TENANT#{tenant}#{shard_for(order_id)}",
        "SK": f"ORDER#{created_at}#{order_id}",
        **attrs,
    })

def list_orders(tenant, limit=50):
    """Return the newest `limit` orders across all shards (first page only)."""
    items = []
    for shard in range(SHARDS):
        kwargs = {
            "KeyConditionExpression": Key("PK").eq(f"TENANT#{tenant}#{shard}"),
            "ScanIndexForward": False,
            "Limit": limit,
        }
        shard_items = []
        while len(shard_items) < limit:
            resp = table.query(**kwargs)
            shard_items.extend(resp["Items"])
            if "LastEvaluatedKey" not in resp:
                break
            kwargs["ExclusiveStartKey"] = resp["LastEvaluatedKey"]
            kwargs["Limit"] = limit - len(shard_items)
        items.extend(shard_items)
    items.sort(key=lambda i: i["SK"], reverse=True)
    return items[:limit]

Each shard is read only until it has limit items, so the function reads at most SHARDS × limit items. That is enough, because the newest limit orders overall must be among the newest limit of some shard. The LastEvaluatedKey loop is still needed because one query response is capped at 1 MB of data.

For a “next page” feature, keep one LastEvaluatedKey per shard and resume each shard from its own cursor. To fetch every order for a tenant instead, remove the limit check and expect to read all items on all shards. In production, run the shard queries in parallel.

What are the GSI best practices?

Add a global secondary index (GSI) only for a proven access pattern. Each GSI repeats every matching write, so it adds write cost and storage. Apply the same uniform-key rule to GSI keys, because a skewed GSI key can throttle writes to the base table.

• Sparse GSIs: only items that carry the GSI key attributes are copied. If only open orders have the key, the index stays small and cheap.
• Index overloading: use generic GSI1PK and GSI1SK so one index serves several entity types.
• GSI write sharding: shard the index key the same way as the table key.
• Narrow projections: use KEYS_ONLY or INCLUDE instead of ALL unless every attribute is needed.

How many GSIs should a table have? As few as your proven access patterns need. The default quota has been 20 GSIs per table, but quotas can change and can be raised on request, so confirm the current number on the DynamoDB quotas page for your Region and account.

What should you know about LSIs and the 10 GB item-collection limit?

A local secondary index (LSI) uses the same partition key as the base table with a different sort key. It must be defined when the table is created, and the default quota has been 5 LSIs per table (confirm on the quotas page).

If a table has an LSI, the 10 GB limit applies to each item collection, meaning all items (and their LSI entries) that share one partition key value. Writes to a collection that reaches the limit are rejected. Tables without an LSI don’t have this cap.

This is why an unbounded collection, such as every order for one tenant under a single partition key, is risky on a table with an LSI. Prefer a GSI when you need an alternate sort order, or bound collections with a time bucket or a shard suffix.

How do you keep queries cheap?

• Use Query, not Scan: Query reads one item collection, while Scan reads the whole table.
• Add ProjectionExpression: return only the attributes you need.
• Use eventually consistent reads: they cost half as much when slightly stale data is acceptable.
• Don’t treat FilterExpression as an index: it filters after reading, so you still pay for all the data read.

Transactions, Consistency, Replication and Streams

Use conditional writes for optimistic concurrency, use TransactWriteItems only where several items must succeed or fail together, and choose the replication model by the consistency you need.

How do conditional writes prevent overwrites?

Add a ConditionExpression to a write, and DynamoDB applies it only if the condition is true. Use attribute_not_exists(PK) to block overwriting an existing item. For optimistic locking, keep a version attribute and write with version = :expected, then increment it.

In plain English: A conditional write is like a ticket office checking the seat is still free at the moment you pay. If someone else took it first, your purchase is refused instead of silently replacing theirs.

When should you use TransactWriteItems?

TransactWriteItems is all-or-nothing across items. Keep it for cases such as moving an order status and writing a ledger item in finance. A transactional read costs 2 RRUs on-demand, against 1 for a strongly consistent read and 0.5 for an eventually consistent one.

C# (.NET)

using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.Model;

// Create one client per process and reuse it.
var client = new AmazonDynamoDBClient();

var orderId = Guid.NewGuid().ToString();

var request = new TransactWriteItemsRequest
{
    ClientRequestToken = orderId, // same token on retry = same request
    TransactItems = new List<TransactWriteItem>
    {
        new TransactWriteItem
        {
            Put = new Put
            {
                TableName = "AppTable",
                Item = new Dictionary<string, AttributeValue>
                {
                    ["PK"] = new AttributeValue { S = "USER#42" },
                    ["SK"] = new AttributeValue { S = $"ORDER#{orderId}" },
                    ["entityType"] = new AttributeValue { S = "Order" }
                },
                ConditionExpression = "attribute_not_exists(PK)"
            }
        },
        new TransactWriteItem
        {
            Update = new Update
            {
                TableName = "AppTable",
                Key = new Dictionary<string, AttributeValue>
                {
                    ["PK"] = new AttributeValue { S = "USER#42" },
                    ["SK"] = new AttributeValue { S = "PROFILE" }
                },
                UpdateExpression = "ADD orderCount :one",
                ConditionExpression = "attribute_exists(PK)",
                ExpressionAttributeValues = new Dictionary<string, AttributeValue>
                {
                    [":one"] = new AttributeValue { N = "1" }
                }
            }
        }
    }
};

try
{
    await client.TransactWriteItemsAsync(request);
}
catch (TransactionCanceledException ex)
{
    foreach (var reason in ex.CancellationReasons)
        Console.WriteLine($"{reason.Code}: {reason.Message}");
}

The order item and the customer counter commit together, or neither does. CancellationReasons tells you which condition failed.

How should you handle retries and pagination?

• Trust SDK retries: The SDKs retry throttled requests with backoff by default, so do not add custom tight retry loops.
• Reuse the client: Keep one client instance per process.
• Paginate: Loop on LastEvaluatedKey for every Query and Scan.

Which replication model fits your consistency needs?

Global tables replicate across Regions. Multi-account global tables (announced Feb 3, 2026) add account-level isolation and separate governance. Multi-Region strong consistency (MRSC) is available in 15 AWS Regions as of the Sept 2026 expansion, so check your Regions first. In Oct 2026 AWS added replica disassociation, which lets a Region or account keep its table as a standalone single-Region table without copying data.

What changed in DynamoDB Streams?

Streams now supports the AT_TIMESTAMP shard iterator (announced Oct 15, 2026). A consumer can start from a point in time instead of only the oldest retained record (up to 24 hours old) or new records. It also works with KCL through the Streams Kinesis adapter.

In a single-table design, route stream consumers by the entityType attribute, so an order handler ignores customer records.

DynamoDB Cost Optimization: On-Demand vs Provisioned and Item Size

Start with on-demand for most workloads. Move to provisioned with auto scaling only when traffic is steady and predictable. Cut cost first by shrinking items and removing unused indexes, because those savings apply in every capacity mode.

Is on-demand or provisioned cheaper in DynamoDB?

After the November 2024 on-demand price reduction, on-demand is commonly the default recommendation. Before that price cut, on-demand was widely seen as much more expensive for steady workloads. Provisioned capacity with auto scaling can still save money for steady traffic, but the gap has narrowed.

In plain English: On-demand is like paying per taxi ride, so you pay only when you travel. Provisioned is like leasing a car: cheaper per trip if you drive every day, wasted money if it sits in the garage.

A secondary summary of the AWS cost-optimization page puts the break-even at about 35% average utilization of provisioned capacity. That figure has not been confirmed against the AWS documentation, so treat it as unverified. It also says on-demand can still win above that level when traffic has quiet periods with occasional peaks. Check the current AWS cost-optimization page and your own CloudWatch usage data before you decide.

The animated diagram below shows the decision path for choosing a capacity mode.

How do the capacity modes compare?

This table compares the three options across the main decision factors.

AWS Database Savings Plans (launched December 2025) are a discount layer on top of a capacity mode, not a third mode. A 1-year commitment gives up to about 18% on on-demand throughput and up to about 12% on provisioned capacity.

What does a read cost on-demand?

Read cost depends on consistency and item size, in 4 KB steps. The table shows the on-demand read units (RRUs) per read of up to 4 KB.

For storage, the source quotes list prices of $0.25 per GB-month for Standard and $0.10 per GB-month for Standard-IA. Confirm prices for your Region on the AWS pricing page.

How do I compare the modes with my own numbers?

Convert your traffic into monthly units, then multiply by the list price for your Region. The formula is requests per second x units per request x seconds in the month x price per unit. This guide does not quote throughput prices, so take them from the AWS pricing page.

The example below uses a simplified workload: a retail catalog service that reads a 6 KB item with strongly consistent reads, averaging 100 reads per second with a peak of 200 reads per second. It assumes a 30-day month (2,592,000 seconds, 720 hours) and provisioned capacity set flat at the peak.

Plug both prices into the last row and compare the two totals. Repeat the same steps for writes, using 1 write unit per 1 KB. If you switch to eventually consistent reads, halve the read units in both columns.

This simplified Python script does the same arithmetic. It asks for the two prices so you can enter the current values for your Region, and you can add your own logic for writes or auto scaling.

Python

import math

SECONDS_PER_MONTH = 30 * 24 * 3600
HOURS_PER_MONTH = 30 * 24


def read_units(item_kb, strongly_consistent=True):
    """Read units for one read: 4 KB blocks, halved for eventual consistency."""
    blocks = math.ceil(item_kb / 4)
    return blocks * (1 if strongly_consistent else 0.5)


def compare_read_cost(avg_rps, peak_rps, item_kb, od_price_per_million, prov_price_per_unit_hour):
    units = read_units(item_kb)
    on_demand_units = avg_rps * units * SECONDS_PER_MONTH
    provisioned_unit_hours = peak_rps * units * HOURS_PER_MONTH
    return {
        "on_demand_cost": on_demand_units / 1_000_000 * od_price_per_million,
        "provisioned_cost": provisioned_unit_hours * prov_price_per_unit_hour,
        "avg_utilization": avg_rps / peak_rps,
    }


od_price = float(input("On-demand price per million read units: "))
prov_price = float(input("Provisioned price per read capacity unit-hour: "))
print(compare_read_cost(100, 200, 6, od_price, prov_price))

The script returns both monthly costs and the average utilization, so you can see which mode is cheaper for your traffic shape.

How do item size and GSIs multiply cost?

A write unit covers 1 KB, so a 6 KB item write costs 6 write units. A strongly consistent read of the same item costs 2 read units (6 KB rounds up to two 4 KB blocks). Every GSI that contains the item repeats the write.

The table shows write units for one 6 KB item under different designs. KEYS_ONLY figures assume the projected keys fit in 1 KB.

Which other levers reduce the DynamoDB bill?

• Standard-IA table class: Use it for data that is stored a lot but read rarely (e.g. old retail orders).
• TTL: Expire old items such as sessions so you stop paying to store them.
• Blobs in S3: Keep only a reference in the item to shrink read and write units.
• Short attribute names: Apply only where item size is truly the cost driver, since they hurt readability.
• Eventually consistent reads: Use them where slightly stale data is acceptable, to halve read cost.
• PITR and backups: Track their storage as its own line item on the bill.

DynamoDB Security, Backups, Monitoring, Anti-Patterns and Production Checklist

Turn on point-in-time recovery (PITR) and deletion protection, give each application least-privilege IAM access, and alarm on throttles before users notice them. DynamoDB has no servers to patch, so most of your production work is access control, recovery and watching the right metrics.

How do you secure a DynamoDB table?

Grant only the actions and keys each application needs, and keep traffic private. The points below cover the main controls:

• Least-privilege IAM: Scope policies to one table, and to specific actions such as dynamodb:GetItem and dynamodb:Query. Avoid dynamodb:* on all tables.
• Key-prefix access: Use the dynamodb:LeadingKeys condition key to limit a caller to partition keys it owns (e.g. one tenant’s TENANT# prefix in a SaaS product).
• Encryption at rest: It is on by default. You do not need to enable it, but check which key type your compliance rules require.
• Private access: Use a VPC gateway endpoint so traffic from your VPC does not travel over the public internet.
• Account isolation: Keep production in its own account. Multi-account global tables help when replicas need separate governance.
• Sensitive data: Do not store secrets or unencrypted personal data (e.g. patient identifiers in a healthcare app) in plain attributes. Keep secrets in a secrets manager.

How do you back up and restore DynamoDB?

Use PITR for continuous recovery inside its retention window, and on-demand backups for long-term copies. Both add storage cost, so treat them as a budget line item.

Note : PITR is like a security camera that records continuously. If someone deletes the wrong rows at 2:10 PM, you rewind to 2:09 PM. It only keeps footage for a limited time, so older copies need on-demand backups.

The retention window is configurable. You set the recovery period in the same PITR specification (the RecoveryPeriodInDays field), so pick a window that matches how long it could take you to notice a bad deployment or a bad delete. Check the current AWS documentation for the allowed range, and remember that a longer window means more backup storage.

The commands below enable PITR and deletion protection on a table named Orders:

AWS CLI

aws dynamodb update-continuous-backups \
  --table-name Orders \
  --point-in-time-recovery-specification PointInTimeRecoveryEnabled=true

aws dynamodb update-table \
  --table-name Orders \
  --deletion-protection-enabled

The first command turns on continuous backups with the default retention window. The second blocks the table from being deleted until you switch protection off.

What does a DynamoDB restore bring back, and what do you reapply?

A restore always creates a new table. By default it brings back the data and the table’s GSIs and LSIs, but not auto scaling, IAM, alarms or TTL, so you must set those up again on the new table.

Keep these settings in infrastructure-as-code so reapplying them is a repeatable step, not a manual checklist. Also check the AWS restore documentation for other table settings (e.g. stream settings and tags) that you may need to review. Rehearse the restore on a schedule so the first time you do it is not during an incident.

What changes for operations and upgrades?

Nothing needs patching. There are no OS settings, memory tuning, maintenance windows or version upgrades, because features ship continuously. Instead, review new announcements during architecture reviews (e.g. Streams AT_TIMESTAMP, vector search, replica disassociation).

Use TTL to expire old items. Expiry is not instant, so filter expired items in reads if stale data would cause problems.

Which metrics should you monitor?

Alarm on throttling and errors first, then watch consumption. Track ThrottledRequests, ReadThrottleEvents, WriteThrottleEvents, SystemErrors, ConsumedReadCapacityUnits, ConsumedWriteCapacityUnits and, for global tables, ReplicationLatency.

Enable CloudWatch Contributor Insights to see the most accessed and most throttled keys. It is the fastest way to confirm a DynamoDB hot partition.

What are the common DynamoDB anti-patterns?

This table maps each mistake to what you will see and how to fix it:

Production readiness checklist

Work through these steps in order before go-live:

1. List access patterns: Test each one with a real Query.
2. Check key cardinality: Confirm traffic spreads evenly across partition keys.
3. Justify every GSI: Document each index and its projection.
4. Set an item size and blob policy: Decide what goes to S3.
5. Choose the capacity mode: Document why.
6. Enable PITR and deletion protection: Set the PITR retention window deliberately, and add TTL where data expires.
7. Apply least-privilege IAM: Use dynamodb:LeadingKeys where callers share a table.
8. Configure alarms: Alert on throttles, and enable Contributor Insights.
9. Run a restore test: Check that the data and GSIs/LSIs are present, then reapply auto scaling, IAM, TTL and alarms from your infrastructure-as-code.
10. Load-test the hottest key: Compare results with the per-partition limits.

Key takeaways

These are the points to remember from the guide, in the order you will usually need them.

• Design from access patterns first: list every read and write before you choose keys. Single-table design is a tool for known, related, high-volume patterns, not a universal rule. Use separate tables when entities scale or fail independently, or when patterns are simple or still changing.
• Use a high-cardinality partition key: one partition is designed for up to 3,000 read units and 1,000 write units per second, and item size counts toward that. Adaptive capacity helps with uneven traffic, but it cannot lift the cap for one hot key. Avoid timestamps and status values as partition keys, and use write sharding when one logical key is genuinely hot.
• Keep GSIs few, sparse and narrowly projected: every GSI repeats the write, so it adds write cost and storage. Add one only for a proven access pattern, and prefer KEYS_ONLY or INCLUDE over ALL. Apply the same even-spread rule to GSI keys, because a skewed index key can throttle base-table writes.
• Prefer Query over Scan: use ProjectionExpression and eventually consistent reads where staleness is acceptable. FilterExpression is not an index, because you still pay for everything it reads before filtering.
• Use the right tool for consistency: use conditional writes for optimistic concurrency, and TransactWriteItems only when several items must succeed or fail together. Transactional reads cost more than normal reads. Pick the global table model (eventual consistency, MRSC or single Region) by the freshness you actually need.
• Start on-demand, then measure: move to provisioned with auto scaling only when traffic is steady and predictable. Check the roughly 35% utilization break-even against the current AWS cost-optimization page and your own usage data, since it comes from a secondary summary. Database Savings Plans are a discount layer on top of a capacity mode, not a third mode.
• Treat item size as a cost driver: keep large blobs in S3 and store only the reference in the item. Use TTL to expire old data and Standard-IA for rarely read tables, and watch PITR and backup storage as a line item.
• Protect and observe the table: enable PITR and deletion protection, apply least-privilege IAM, and alarm on throttle metrics. Use Contributor Insights to confirm hot keys, and run restore tests on a schedule.
• Review new features when you revisit the design: DynamoDB has no versions, so check announcements such as multi-account global tables, MRSC, replica disassociation, Streams AT_TIMESTAMP and vector search. Each may simplify an architecture you built around older limits.

FAQ

Is single-table design always the best approach in DynamoDB?

No. Single-table design pays off when your access patterns are known, related and high volume, because one Query can return several entity types from the same partition key. Use separate tables when entities scale or fail independently, need separate IAM, backup scope or blast radius, or when the access patterns are simple or still changing.

How do I choose a good partition key in DynamoDB?

Choose an attribute with high cardinality (many distinct values) whose traffic is spread evenly, and that matches your main lookup, such as customerId or orderId. Avoid timestamps and status or boolean values, because they send most traffic to a few key values. Apply the same rule to the keys of your GSIs, since a skewed index key can throttle base-table writes.

What is a hot partition and how do I fix it?

A hot partition is a partition that receives more traffic than its limit, so requests get throttled even when the table as a whole is well under its capacity. Confirm it with CloudWatch Contributor Insights, which shows the most accessed and most throttled keys. Then fix it with a better partition key, write sharding (a calculated suffix that spreads one logical key across N keys), or caching for read-heavy keys. Adaptive capacity helps uneven traffic, but it cannot lift the hard limit for a single hot key.

What are the throughput limits per partition in DynamoDB?

A partition is designed to deliver up to 3,000 read units and 1,000 write units per second, and item size counts toward both limits. A read unit is one strongly consistent read (or two eventually consistent reads) per second for an item up to 4 KB. For example, a 20 KB item costs 5 read units per strongly consistent read, so about 600 reads per second on that one item reaches the partition limit.

Should I use on-demand or provisioned capacity?

Start with on-demand for most workloads, because it needs no capacity planning and has lower throttling risk for spiky traffic. Move to provisioned with auto scaling when traffic is steady and predictable. One secondary summary of AWS guidance puts the break-even at roughly 35% average utilization of provisioned capacity, so check that figure against the current AWS cost-optimization page and your own usage data. AWS Database Savings Plans are a discount on top of either mode, not a third mode.

That’s all! Happy coding! Did this DynamoDB best practices guide help you solve your design or cost issue? Please share your questions or experience in the comments below. Bookmark this page and share it with your team, and subscribe to TheCodeBuzz for more database best-practice guides.

Sources and further reading

• Best practices for designing and using partition keys effectively in DynamoDB (AWS Documentation (Amazon DynamoDB Developer Guide))
• Best practices – AWS Prescriptive Guidance (DynamoDB data modeling) (AWS Prescriptive Guidance)
• Amazon DynamoDB now supports real-time vector search (AWS What’s New)
• Amazon DynamoDB global tables now support disassociating replicas (AWS What’s New)
• Amazon DynamoDB Streams now supports timestamp-based stream processing (AWS What’s New)

The post DynamoDB Best Practices: Single-Table Design, Keys and Cost first appeared on TheCodeBuzz.

The scope includes query-first modeling, partition key design, Storage-Attached Indexes (SAI), consistency levels, lightweight transactions (LWT) and Accord, tombstones, compaction, drivers, security, repair, backups, monitoring and upgrades. Every rule comes with the reason behind it, so you can judge when it fits your workload and when it does not.

Many popular guides still carry pre-5.0 advice. This guide adds what they often miss: the limits of SAI, UCS versus the STCS default, repair tied to gc_grace_seconds, driver settings, security and restore testing. It is written for engineers, architects and DBAs who run Cassandra in production.

For the version baseline, Apache Cassandra 5.0 is the latest GA series (5.0.9, released 2026-08-07), and 4.1 is the previous stable line (4.1.12). The 3.x series is end-of-life. Cassandra 6.0 is still pre-GA (6.0-alpha3) and is not for production.

Version note: This guide targets Apache Cassandra 5.0.9 (latest GA) and 4.1.12 (previous stable line), and treats 6.0-alpha3 as pre-GA only.

 

In this guide

 

• Cassandra Best Practices at a Glance
• Cassandra Data Modeling Best Practices and Partition Key Design
• Indexing in Cassandra 5.0: SAI, Secondary Indexes or More Tables
• Consistency Levels and Replication Factor: Choosing LOCAL_QUORUM
• Transactions and Lightweight Transactions: Paxos v2 and Accord in Cassandra 6.0
• Tombstones, TTL and gc_grace_seconds: Deleting Data Safely
• Choosing a Compaction Strategy: STCS, LCS, TWCS or UCS
• Drivers, Connection Management and Security
• Repair, Backup and Restore Best Practices
• Operations, Monitoring and Upgrades
• Common Cassandra Anti-Patterns
• Cassandra Production Readiness Checklist
• Key takeaways
• FAQ

Cassandra Best Practices at a Glance

Apache Cassandra is a distributed, wide-column database built for high write throughput and availability across nodes and datacenters. Today in this guide, we will see Cassandra data modeling best practices, consistency, indexing, repair, backups and upgrades in one place.

Note: A partition is like one drawer in a filing cabinet. Every row with the same partition key goes into the same drawer, and that drawer lives on specific nodes. Unlike a real cabinet, each drawer is copied to several nodes, so one failure doesn’t lose it.

Best Practices Summary Table

The table below lists the main areas, what to do and what to avoid. Each row is explained in its own section later.

Which Cassandra Version Does This Guide Assume?

This guide uses the versions below as its baseline.

• 5.0.9: the latest GA release, and the preferred target.
• 4.1.12: the latest on the previous stable line.
• 6.0-alpha3: pre-GA and not for production.
• Java: Java 11 and 17 are used with Cassandra 5.0.x.

Cassandra Data Modeling Best Practices and Partition Key Design

Design your tables from your queries, not from your entities. A good Cassandra model has three goals: spread data evenly with a high-cardinality partition key, bound partition size, and read as few partitions as possible, ideally one per query.

Why should a query read only one partition?

A single-partition read goes to the replicas that own that partition. A multi-partition read makes the coordinator (the node handling the request) contact several nodes and wait for the slowest one. That adds latency variance, so the occasional slow response hurts your tail latency.

How do you choose the partition key and clustering columns?

The partition key decides which nodes hold the data. Clustering columns decide the sort order of rows inside that partition. Pick the partition key from the column your query always filters by with equality, and pick clustering columns from the sort or range you need.

Example: a retail app shows “my orders, newest first”. The table below shows how the choice maps.

How big should a partition be?

Keep partitions under about 100 MB and under about 100,000 items. The hard practical limit is 2 billion cells per partition, but you should never plan to get near it.

Oversized partitions hurt in several ways:

• Heavy reads: the node must scan and merge more data for each request.
• Compaction and repair pressure: large partitions take longer to merge and to compare between replicas.
• Hot nodes: one partition lives on only a few replicas, so one big partition loads those nodes unevenly.

How does bucketing keep partitions bounded?

Bucketing means adding a column, such as a day or hour, to the partition key so a busy key stops growing forever. One IoT sensor writing every second would otherwise build a single unbounded partition.

In plain English: Think of a ledger where you start a new page every day. You never end up with one endless page, and you can still find any day quickly. The catch is that a question spanning ten days means opening ten pages.

Here is a simplified sensor table with a day bucket in the partition key, followed by a single-partition read:

CQL

CREATE TABLE iot.sensor_readings (
    sensor_id    text,
    day_bucket   date,
    reading_time timestamp,
    temperature  double,
    PRIMARY KEY ((sensor_id, day_bucket), reading_time)
) WITH CLUSTERING ORDER BY (reading_time DESC);

SELECT reading_time, temperature
FROM iot.sensor_readings
WHERE sensor_id = 'sensor-1001'
  AND day_bucket = '2026-10-20'
LIMIT 100;

✅ One partition, newest readings first, and each partition holds at most one day of data per sensor.

The trade-off: a query over several days now touches several partitions. The application must list the buckets and query each one explicitly (e.g. seven queries for a week). Choose a bucket size so a partition stays within the limits above at your peak write rate.

What are hot partitions and how do you avoid them?

A hot partition is one that receives a disproportionate share of traffic. Low-cardinality keys such as country or status create them, because millions of rows share a few key values and land on a few nodes. Use a key with many distinct values, and add a bucket if one value is still very busy.

Is denormalization normal in Cassandra?

Yes. Cassandra has no joins, so you store the same data in several tables, one per query (e.g. orders_by_customer and orders_by_date). One write to several tables is cheaper than a read that must gather data from many partitions.

Use a logged batch only to keep those denormalized tables in sync, because it guarantees all writes eventually apply. Don’t use it for speed. A batch across many partitions adds work on the coordinator.

Why avoid ALLOW FILTERING and full scans?

ALLOW FILTERING lets a query run without a full partition key, so Cassandra reads many partitions and discards rows that don’t match. Cost grows with table size, and latency becomes unpredictable. Keep it out of application paths. If you need the query often, create a table for it instead.

Indexing in Cassandra 5.0: SAI, Secondary Indexes or More Tables

Use denormalized tables for hot, latency-critical queries. Use Storage-Attached Indexes (SAI), new in Cassandra 5.0, for secondary lookups where a partition-key query is not possible. Avoid legacy secondary indexes (2i) in new designs.

What is SAI in Cassandra 5.0?

SAI is an index attached to the SSTables of a table. It lets you filter on non-key columns without creating a separate table. The 5.0 feature list also includes a vector data type with similarity functions, which builds on SAI.

In plain English: A denormalized table is a second filing cabinet sorted the way you search. SAI is a small index card stapled to each existing drawer, so you can look things up by another field. The cards help, but you still have to know which drawers to open.

Denormalized table, SAI or legacy index?

The table below compares the three options across cost and limits.

What are the limits of SAI?

An SAI query with no partition key may fan out across nodes, so it adds latency variance. SAI does not remove the need for Cassandra data modeling best practices. Test every SAI query on production-size data before you rely on it, because small test sets hide fan-out cost.

When should you pick which?

• Primary query: “orders by customer” is the main read path, so build it as a table keyed by customer.
• Secondary filter: “find orders by status in this customer’s partition” is fine with SAI plus a partition restriction (e.g. a retail support screen).
• Cross-partition search: Use SAI only if the latency variance is acceptable. Otherwise add another table.

Here is a simplified example that indexes the status column and queries it inside one customer partition:

CQL

CREATE TABLE IF NOT EXISTS shop.orders_by_customer (
  customer_id uuid,
  order_id timeuuid,
  status text,
  total decimal,
  PRIMARY KEY ((customer_id), order_id)
) WITH CLUSTERING ORDER BY (order_id DESC);

CREATE INDEX IF NOT EXISTS orders_status_sai
  ON shop.orders_by_customer (status) USING 'sai';

SELECT order_id, status, total
FROM shop.orders_by_customer
WHERE customer_id = 7b1f3c52-8a6e-4c1d-9d0e-3f2a5b6c7d88
  AND status = 'SHIPPED';

The query returns only the shipped orders for that one customer. The partition key restriction keeps it on the replicas of a single partition, and SAI handles the status filter.

Consistency Levels and Replication Factor: Choosing LOCAL_QUORUM

For most multi-datacenter production workloads, use RF=3 per datacenter with LOCAL_QUORUM for both reads and writes. RF=3 lets a quorum form from two agreeing replicas, tolerates one node failure and allows rolling restarts without downtime.

What is a consistency level?

A consistency level is the number of replicas that must confirm a read or write before Cassandra reports success to the client. You choose it per request, so different queries can make different trade-offs.

Note : Three people hold a copy of the same record. A consistency level decides how many of them must say “done” before you accept the answer, like a committee that needs a majority vote. The analogy stops fitting in one place: Cassandra still sends the write to all copy-holders, it only waits for some of them.

How do QUORUM and LOCAL_QUORUM differ?

QUORUM needs RF/2 + 1 replicas (integer division) across all datacenters. LOCAL_QUORUM needs a majority only in the coordinator’s datacenter, which is 2 of 3 with RF=3.

With two datacenters at RF=3, there are six replicas in total, so QUORUM needs four. That forces at least one cross-datacenter acknowledgment. LOCAL_QUORUM avoids that WAN latency and keeps working if the other datacenter is completely down. The animated diagram below shows a LOCAL_QUORUM write, including the case where DC2 is unavailable.

Which consistency level fits which use case?

The table assumes two datacenters with RF=3 each (six replicas in total).

When do you get strong consistency?

You get strong consistency when read replicas plus write replicas is greater than RF. With RF=3, LOCAL_QUORUM on both sides gives 2 + 2 = 4, which is more than 3, so every read overlaps at least one replica that saw the latest write. This gives read-your-writes within that datacenter.

Know the trade-offs. ALL fails as soon as one replica is down, so one node restart becomes an outage. ONE is fast but can return stale data. Use lower levels only where staleness is acceptable, such as video view counters on a media site. Use LOCAL_QUORUM for order and payment data in a retail system.

How do you set replication correctly?

Use NetworkTopologyStrategy with an explicit RF per datacenter, and make sure the snitch reports correct datacenter and rack names. Do not use SimpleStrategy in production multi-datacenter clusters, because it ignores topology and can place all replicas in one rack or datacenter.

The example below creates a keyspace with RF=3 in each datacenter, then sets the session consistency in cqlsh:

CQL

CREATE KEYSPACE retail
  WITH replication = {
    'class': 'NetworkTopologyStrategy',
    'dc1': 3,
    'dc2': 3
  };

CONSISTENCY LOCAL_QUORUM;

Each datacenter keeps three replicas, and every later read or write in this cqlsh session waits for two local replicas. The names dc1 and dc2 must match the datacenter names your snitch reports.

Transactions and Lightweight Transactions: Paxos v2 and Accord in Cassandra 6.0

Cassandra gives you atomicity and isolation per partition. For compare-and-set on a single partition it offers lightweight transactions (LWT, written as IF conditions). It is not a general ACID database today.

When should you use a lightweight transaction?

Use LWT only where two writers must not both succeed, such as a unique username or an inventory reservation. Paxos, the consensus protocol behind LWT, needs several round trips between replicas, so it costs far more than a normal write. Don’t make it your default write path.

In plain English: A normal write is like dropping a note in a mailbox. An LWT is like getting every committee member to agree out loud before the note is filed. It is safer, but it takes much longer.

Example: a bank checks that an email is unused before opening an account. The check and the insert must happen as one step, as shown below.

CQL

CREATE TABLE IF NOT EXISTS bank.users_by_email (
  email text PRIMARY KEY,
  user_id uuid,
  created_at timestamp
);

SERIAL CONSISTENCY LOCAL_SERIAL;

INSERT INTO bank.users_by_email (email, user_id, created_at)
VALUES ('asha@example.com', uuid(), toTimestamp(now()))
IF NOT EXISTS;

The result has an [applied] column. True means the row was inserted. False means the email already exists, and the existing row is returned. Always check this column in your application code. LOCAL_SERIAL limits the Paxos phase to the local datacenter, and SERIAL spans all datacenters.

Which Paxos settings should you set in production?

Set paxos_variant to v2 together with paxos_state_purging set to repaired. The two settings are independent, so set both deliberately. Test the change in staging and follow the official upgrade notes for your exact version.

What does Accord in Cassandra 6.0 add?

Accord adds multi-partition, strict-serializable transactions through BEGIN TRANSACTION. Cassandra 6.0 is still pre-GA (6.0-alpha3), and Accord is beta and off by default. It requires Transactional Cluster Metadata and doesn’t support counter tables. It also rejects LOCAL_QUORUM, TWO and THREE for Accord operations. Don’t plan production designs on it yet, because 5.0.9 remains the current GA release.

Plain writes, logged batch, LWT or Accord: how do they compare?

This table compares the four options by scope, isolation, cost and status.

Tombstones, TTL and gc_grace_seconds: Deleting Data Safely

A delete in Cassandra writes a tombstone, a marker saying the data is deleted, instead of removing it right away. Tombstones are purged only after gc_grace_seconds (default 864000 seconds, 10 days) has passed and only when compaction runs. Until then, reads must scan them, so heavy deletes slow reads.

In plain English: A tombstone is a crossed-out line in a ledger. The old line stays on the page, and the crossing-out is only cleaned up when the ledger is rewritten. Unlike a ledger, Cassandra keeps copies on several nodes, and every copy must see the crossing-out.

Why must repair finish within gc_grace_seconds?

If a replica misses a delete and the other replicas purge their tombstones, that replica becomes the only holder of the row. The next read or repair copies the old value back, and the deleted row returns as zombie data. Repair inside the grace window prevents this.

The animated diagram below shows a delete across three replicas, with the healthy path and the zombie failure path side by side.

What creates tombstones?

These patterns produce most tombstone problems in production:

• Queue-style tables: rows are inserted, read and deleted in the same partition, so reads scan many dead entries.
• Frequent deletes: every delete adds a marker that stays for at least the grace period.
• Partial deletes in wide partitions: row or range deletes inside a large partition leave many markers next to live data.
• Null writes: explicitly inserting null writes a tombstone. Leave the column out of the statement, or pass the driver’s unset value (e.g. UNSET_VALUE in the Python driver).

How do you delete data safely?

1. Use TTL instead of DELETE: let data expire on its own schedule. Cassandra 5.0 also extends the maximum TTL, which helps for long retention.
2. Bucket by time: put a day or hour bucket in the partition key so old data sits in partitions you stop reading.
3. Avoid large range deletes: they leave wide tombstones that every read must check.
4. Use TWCS for TTL-heavy data: when data is time-windowed and not updated out of order, whole expired SSTables can be dropped.

Example: a retail site keeps cart-activity events for seven days. TTL plus TWCS removes them without any application delete.

CQL

CREATE TABLE shop.cart_events (
    user_id    uuid,
    day_bucket date,
    event_time timestamp,
    event_type text,
    PRIMARY KEY ((user_id, day_bucket), event_time)
) WITH CLUSTERING ORDER BY (event_time DESC)
  AND default_time_to_live = 604800
  AND compaction = {
    'class': 'TimeWindowCompactionStrategy',
    'compaction_window_unit': 'DAYS',
    'compaction_window_size': 1
  };

INSERT INTO shop.cart_events (user_id, day_bucket, event_time, event_type)
VALUES (uuid(), '2026-10-20', toTimestamp(now()), 'add_to_cart')
USING TTL 86400;

The table default expires rows after seven days, and the insert overrides it with a one-day TTL. Each daily window becomes its own SSTable group that can be dropped as a whole.

How do you catch tombstone problems early?

Set the tombstone warn and failure thresholds in cassandra.yaml and review the guardrails available in your version. Check nodetool tablestats for average and maximum tombstones per slice, and watch the logs for tombstone warnings.

Warning: Don’t lower gc_grace_seconds just to purge faster. A shorter value frees space sooner, but it raises the risk of zombie data unless repair completes more often than the new value. Lower it only after your repair schedule is proven to beat it.

Choosing a Compaction Strategy: STCS, LCS, TWCS or UCS

STCS is still the default in Cassandra 5.0, but the UCS documentation recommends the Unified Compaction Strategy (UCS) for most workloads. UCS can also be configured to behave like the older strategies. If you stay on classic strategies, use TWCS for TTL-heavy time-series data.

What does compaction do?

Compaction is the background process that merges SSTables (the immutable data files on disk) to drop overwritten data and expired tombstones. The strategy you pick decides which files get merged and when.

In plain English: Think of many small notebooks piling up on a desk. Compaction copies the latest notes into fewer, cleaner notebooks and throws the old ones away. The strategy is the rule for which notebooks you tidy together, and how often.

How do the four strategies compare?

The animated diagram below walks through the decision for one table, and the table after it compares the strategies in qualitative terms.

Why do the strategies behave differently?

• LCS: keeps data in small sorted levels, so a read touches few files. You pay with more write I/O.
• STCS: favors writes by merging files of similar size. Large merges need free disk space while they run.
• TWCS: groups data into time windows and drops a whole SSTable once everything in it has expired. This only works if data isn’t updated or deleted out of order.

How do you migrate a table to UCS?

1. Test first: try the change on a non-production cluster with realistic data.
2. Change per table: use ALTER TABLE, one table at a time.
3. Mimic your current strategy: start with settings that behave like STCS or LCS, then tune.
4. Watch the switch: track pending compactions and disk use while it runs.

Parameter names and defaults can change between versions, so confirm them in the official UCS documentation for your release. The T4 value below is the STCS-like setting from the 5.0 docs.

CQL

-- UCS, configured to behave like STCS
ALTER TABLE shop.orders_by_customer
WITH compaction = {
  'class': 'UnifiedCompactionStrategy',
  'scaling_parameters': 'T4'
};

-- TWCS for TTL-heavy time-series data
ALTER TABLE iot.sensor_readings
WITH compaction = {
  'class': 'TimeWindowCompactionStrategy',
  'compaction_window_unit': 'DAYS',
  'compaction_window_size': 1
};

Each statement changes the strategy for one table only. Then check progress on each node:

bash

nodetool compactionstats

This shows pending tasks and running compactions. A pending count that keeps growing after the switch means the node can’t keep up.

Cassandra 5.0 also adds trie memtables and trie SSTables. They are separate storage features from compaction, and you can evaluate them on their own.

Drivers, Connection Management and Security

Use one long-lived session per application, prepared statements, token-aware and datacenter-aware load balancing, and an explicitly set local datacenter. Turn on authentication, authorization and TLS from day one, because adding them later means a risky rolling change on a live cluster.

How should you manage connections?

Create the Session once at startup and share it across all requests. Opening one per request wastes connections and adds handshake latency. A prepared statement is parsed once on the server, and it lets the driver work out which replicas own the partition.

In plain English: Token-aware routing is like a courier who knows which house holds the parcel and goes straight there, instead of leaving it at a front desk that must pass it on. The “front desk” is the coordinator, and skipping it saves one network hop.

Set the local datacenter explicitly so traffic never reaches a remote DC by accident. Enable retries and speculative execution (sending a second request when the first is slow) only for idempotent statements, meaning ones that are safe to run twice.

The table below lists the driver settings to check, with the value to use and the reason:

How do you configure the Python driver?

Here is a simplified example using ExecutionProfile, the current way to set policies and consistency:

Python

import os
import ssl
from cassandra import ConsistencyLevel
from cassandra.auth import PlainTextAuthProvider
from cassandra.cluster import Cluster, ExecutionProfile, EXEC_PROFILE_DEFAULT
from cassandra.policies import DCAwareRoundRobinPolicy, TokenAwarePolicy

profile = ExecutionProfile(
    load_balancing_policy=TokenAwarePolicy(DCAwareRoundRobinPolicy(local_dc="dc1")),
    consistency_level=ConsistencyLevel.LOCAL_QUORUM,
    request_timeout=5.0,
)

cluster = Cluster(
    ["10.0.0.1", "10.0.0.2"],
    auth_provider=PlainTextAuthProvider("app_user", os.environ["CASS_PASSWORD"]),
    ssl_context=ssl.create_default_context(cafile="ca.pem"),
    execution_profiles={EXEC_PROFILE_DEFAULT: profile},
)
session = cluster.connect("shop")  # create once, reuse everywhere

stmt = session.prepare("SELECT * FROM orders_by_customer WHERE customer_id = ?")
stmt.is_idempotent = True
rows = session.execute(stmt, [customer_id])

✅ One shared session, local DC set, LOCAL_QUORUM by default, TLS on, and a prepared read marked idempotent.

How do you configure the C# driver?

With the DataStax C# driver (CassandraCSharpDriver), build the Cluster once and register the session as a singleton:

C#

using Cassandra;

var cluster = Cluster.Builder()
    .AddContactPoints("10.0.0.1", "10.0.0.2")
    .WithLocalDatacenter("dc1")
    .WithCredentials("app_user", Environment.GetEnvironmentVariable("CASS_PASSWORD"))
    .WithSSL()
    .Build();

var session = await cluster.ConnectAsync("shop"); // singleton

var prepared = await session.PrepareAsync(
    "SELECT * FROM orders_by_customer WHERE customer_id = ?");

var bound = prepared.Bind(customerId)
    .SetConsistencyLevel(ConsistencyLevel.LocalQuorum)
    .SetIdempotence(true);

RowSet rows = await session.ExecuteAsync(bound);

The local DC is named, the statement is prepared and bound, and consistency is LocalQuorum.

How do you secure a Cassandra cluster?

Enable PasswordAuthenticator and CassandraAuthorizer in cassandra.yaml. Create your own superuser, then disable or drop the default cassandra role. Give each application a role with only the permissions it needs.

CQL

CREATE ROLE analyst WITH PASSWORD = 'use-a-strong-secret' AND LOGIN = true;
GRANT SELECT ON KEYSPACE clinic TO analyst;

• TLS: Enable client-to-node and node-to-node encryption. Use mutual TLS where you control the clients.
• Dynamic data masking (5.0): Hides sensitive column values from roles without unmask rights. Example: mask patient identifiers for analyst roles in a healthcare system.
• CIDR authorizer (5.0): Limits which networks a role can connect from.
• Guardrails: Added in 4.1 and extended in 5.0, they set warn and fail limits that stop risky operations, such as oversized partitions or too many tables.

Repair, Backup and Restore Best Practices

Run repair on every node within each gc_grace_seconds window. With the default of 864000 seconds that means at least once every 10 days, and in practice more often to leave a safety margin. Take scheduled snapshots with retention, enable commit log archiving for point-in-time restore, and test restores regularly.

What does Cassandra repair do?

Repair compares the replicas of the same data using Merkle trees (hash trees that summarize ranges of data) and streams any differences between nodes. It fixes data that a replica missed, for example while the node was down.

In plain English: Three people each keep a copy of the same notebook. Repair is the meeting where they compare page summaries, find pages that differ, and fill in the gaps. Unlike real people, the nodes compare hashes first, so they only copy the pages that really differ.

How should you schedule repair?

Run repair regularly in small pieces instead of rarely in one large job. Follow these rules:

• Prefer incremental repair: on versions that support it, it only checks data not yet repaired. Use full repair only when the release notes or a recovery task call for it.
• Use -pr on every node: the primary-range option repairs only the ranges a node owns first, so the same data isn’t compared three times.
• Go node by node: running repair on all nodes at once adds heavy streaming and compaction load.
• Automate it: open-source Cassandra has no NodeSync equivalent from DSE. Auto Repair (built-in scheduling) arrived in the 5.0.8+ backport and needs explicit opt-in. Otherwise use an external scheduler. Verify against the release notes for your exact version before enabling.
• Watch TTL-heavy tables: expired data becomes tombstones, and a replica that missed one can bring old values back after the purge. This is the same zombie-data risk described in the tombstones section.

Here is a simplified example of repairing the primary ranges of one keyspace on the current node:

BASH

nodetool repair -pr shop_ks

✅ Repairs only the ranges this node owns. Repeat on the next node when it finishes.

Which backup method should you use?

Use snapshots as the base and add commit log archiving if you need point-in-time recovery. The table compares the four common methods:

Take a named snapshot, then copy it off the node:

BASH

nodetool snapshot -t daily_2026-10-20 shop_ks

Creates a snapshot tagged daily_2026-10-20 for every table in shop_ks. Store it off the node, because a snapshot on the same disk does not survive disk loss.

How do you restore and test a backup?

Restore the schema first, then the data, then run repair. The animated diagram below shows the full restore flow, step by step.

A restore test loads schema, snapshot SSTables and archived commit logs into a fresh cluster, then repairs and validates row counts against the source.

1. Restore the schema: apply the saved CQL so tables exist.
2. Load the data: stream SSTables with sstableloader, or copy files into the table directory and run nodetool refresh.
3. Replay commit logs: stop at the target timestamp for point-in-time recovery.
4. Repair and validate: run repair, then compare row counts with the source.

BASH

sstableloader -d 10.0.1.11,10.0.1.12 /restore/shop_ks/orders_by_customer

Streams the SSTables in that directory to the live cluster. The path must end in keyspace/table.

A backup that was never restored is untested. Run the restore on a separate cluster on a schedule, and time it. For example, a retail team can check that last night’s order tables match production before trusting the backup for peak season.

Operations, Monitoring and Upgrades

Run a supported Java version, keep OS and disk settings aligned with Cassandra’s recommendations, watch partition size and pending compactions, and upgrade by rolling one node at a time to a supported release line. The sections below cover each of these.

Which Java, disk and OS settings should you check?

Cassandra 5.0.x runs on Java 11 and Java 17. Pick one of them and use it on every node.

• Disks: Put the commit log and data directories on separate disks where possible, so sequential commit log writes don’t compete with compaction and reads.
• Free space: Keep free disk for compaction. STCS in particular needs spare room when it merges large SSTables.
• Heap: Start from the JVM options files shipped with your version, not values copied from old blog posts. Those were tuned for other Java and Cassandra releases.
• Swap and limits: Disable swap and raise ulimits and file-descriptor limits as the Cassandra docs recommend.
• Clocks: Run NTP or chrony on every node. Cassandra resolves conflicting writes by timestamp, so a drifting clock can make an older write win.

What should you monitor?

Start with partition size and compaction backlog, then add latency and GC. The table shows each signal and what to do about it.

Use these commands to find oversized partitions:

Bash

# Partition size and cell count percentiles for one table
nodetool tablehistograms retail orders_by_customer

# Look for "Compacted partition maximum bytes" in the output
nodetool tablestats retail.orders_by_customer

The first command shows percentile distributions. The second gives the largest partition on that node.

How do you upgrade Cassandra safely?

Upgrade one node at a time, one major version at a time. Versions 3.0 and 3.11 reached end-of-life when 5.0 went GA on September 5, 2024, so plan to leave them. The 4.1 line is at 4.1.12, the 4.0 line is at 4.0.21, and 5.0.9 is the current GA. Don’t run 6.0-alpha3 in production.

In plain English: A rolling upgrade is like renovating a hotel one room at a time. Guests keep using the other rooms, so the hotel never closes. It only works if the other rooms are in good shape, which is why you repair first.

1. Read NEWS.txt: Check the target version for required steps and breaking changes.
2. Snapshot: Take a snapshot on every node.
3. Repair and check health: Finish a repair and confirm all nodes are up.
4. Freeze schema: Make no schema changes until every node is upgraded.
5. Roll each node: Drain, stop, upgrade, start, then check.
6. Rewrite SSTables if needed: Run upgradesstables only when the release notes ask for it.

This is the command sequence for one node:

Bash

nodetool snapshot -t pre_upgrade retail
nodetool drain                      # flush memtables, stop accepting writes
sudo systemctl stop cassandra
# install the new Cassandra package or binaries here
sudo systemctl start cassandra
nodetool status                     # wait for UN (Up/Normal) before the next node
nodetool upgradesstables            # only if the release notes require it

Streaming during node operations is faster since 4.0, because zero-copy streaming sends eligible whole SSTables without rewriting them.

Common Cassandra Anti-Patterns

These are the mistakes that most often cause slow reads, hot nodes and data resurrecting. Each row below names the symptom you will see and the fix, with a pointer to the section that explains the reason.

In plain English: An anti-pattern is a habit that looks fine on day one and hurts later. Think of a shop that stacks every receipt in one box: it works for a week, then finding anything takes all afternoon.

The table lists 15 Cassandra anti-patterns, the symptom of each, and the fix.

Which anti-patterns should you fix first?

Start with the ones that can lose or resurrect data: skipped repair and untested snapshots. Then fix partition design, because a bad partition key is the hardest thing to change once data exists. Driver settings and consistency defaults are cheap to correct and worth doing early.

Cassandra Production Readiness Checklist

Use this Cassandra production checklist as a go-live gate. Each item has a check you can run or verify, so you can mark it done or not done. Any item you can’t verify is a risk to note before launch.

Cluster and Driver Setup

These items confirm the cluster layout and how clients connect to it.

1. Supported version: every node runs a supported line, preferably 5.0.x (5.0.9 is the latest GA). No 3.x nodes and no 6.0-alpha builds.
2. Replication: DESCRIBE KEYSPACE shows NetworkTopologyStrategy with RF=3 in each datacenter.
3. Driver settings: the local datacenter is set explicitly and the default consistency is LOCAL_QUORUM. One long-lived session is shared by the application.
4. Host settings: the JVM is on Java 11 or 17, swap is off, ulimits are raised, and NTP or chrony reports synced clocks on every node.

Data Model and Storage

These items catch the design problems that are expensive to fix after launch.

5. Query shape: each application query reads one partition, and none uses ALLOW FILTERING.
6. Partition size: nodetool tablehistograms and tablestats show compacted partition maximum bytes under about 100 MB.
7. Bounded keys: no partition key grows forever. A time bucket is in the key wherever volume is unbounded.
8. Table settings: every table has a deliberate TTL and compaction strategy (UCS, or TWCS for TTL-heavy data).

Recovery and Upgrades

These items prove you can recover from failure and keep deleted data deleted.

9. Repair: the schedule covers every node within gc_grace_seconds (864000 seconds by default), with a safety margin.
10. Backups: snapshots run on a schedule with retention, are copied off the node, and commit log archiving is on.
11. Restore test: a restore into a separate cluster has been completed and timed, and the time is written down.
12. Upgrade runbook: a written rolling-upgrade procedure exists and has been rehearsed in staging.

Security and Monitoring

These items keep the cluster protected and give you early warning.

13. Access control: authentication, authorization and TLS (client-to-node and node-to-node) are enabled, and the default cassandra superuser is replaced.
14. Guardrails: warn and fail limits are configured, for example for partition size and table count.
15. Alerts: alerts fire on latency percentiles, pending compactions, disk usage and dropped messages, and each alert has a named owner.

Key takeaways

These are the points to remember from this guide before you take a Cassandra cluster to production:

• Model from queries: design one table per query, and accept denormalization. Cassandra has no joins, so one write to several query tables is cheaper than reads that need many partitions.
• Bound your partitions: keep each partition under about 100 MB and about 100,000 items. Add a time bucket (e.g. day or hour) to the partition key for busy keys, and check the real size with nodetool tablehistograms and tablestats.
• Use LOCAL_QUORUM with RF=3: set NetworkTopologyStrategy with RF=3 per datacenter, and use LOCAL_QUORUM for reads and writes. This gives read-your-writes inside the datacenter, tolerates one node down and avoids cross-DC latency.
• Prefer TTL over deletes: explicit deletes and null writes create tombstones that slow reads. Use TTL, time bucketing and TWCS for time-series data instead.
• Finish repair inside gc_grace_seconds: the default is 864000 seconds (10 days). If repair is late, a replica that missed a delete can bring the old data back. Schedule it with the opt-in Auto Repair (5.0.8+) or an external scheduler.
• Test your restores: schedule snapshots with retention, store them off the node, archive commit logs for point-in-time recovery, and restore into a separate cluster on a schedule. A backup that was never restored is untested.
• Pick compaction and indexes deliberately: STCS is still the 5.0 default, but UCS is recommended for most workloads, and TWCS suits TTL-heavy data. SAI helps with secondary lookups, but it does not replace query-first modeling. Test both on production-size data first.
• Stay on supported, GA releases: 5.0.9 is the current GA release, and 3.x is end-of-life. Treat Accord and Cassandra 6.0 (still 6.0-alpha3) as pre-GA, and keep them out of production designs.

That’s all! Happy coding!

Did this Cassandra best practices guide help you? Please share your questions and your own experience in the comments below.

Bookmark this page for your next production review, and share it with your team. Subscribe to TheCodeBuzz for more database best practices guides.

FAQ

What is the ideal partition size in Cassandra?

Keep each partition under about 100 MB and under about 100,000 items. The hard practical limit is 2 billion cells per partition, but you should stay far below it. Check real sizes with nodetool tablehistograms and nodetool tablestats (look at the compacted partition maximum bytes), and add a time bucket to the partition key if a partition keeps growing.

Which consistency level should I use in production, QUORUM or LOCAL_QUORUM?

Use LOCAL_QUORUM for multi-datacenter clusters, with RF=3 in each datacenter. It needs a majority (2 of 3) in the coordinator’s datacenter only, so it avoids cross-DC latency and keeps working if another datacenter is down. QUORUM counts replicas across all datacenters, and EACH_QUORUM is supported for writes only.

How often should I run nodetool repair, and why must it finish within gc_grace_seconds?

Run repair on every node at least once within each gc_grace_seconds window, which is 10 days (864000 seconds) by default. In practice, repair more often to leave a safety margin. If a replica missed a delete and the tombstone is purged on the other replicas, the old value can come back as zombie data. Cassandra 5.0.8 and later include Auto Repair, which needs explicit opt-in, so check the release notes for your exact version before enabling it.

Should I use Storage-Attached Indexes (SAI) or denormalize into more tables?

Denormalize into tables for your hot, latency-critical queries, and use SAI for secondary lookups where a partition-key query is not possible. Avoid legacy secondary indexes (2i) in new designs. An SAI query without a partition key restriction can fan out across nodes and add latency variance, so test it on production-size data.

Does Cassandra support ACID transactions, and what changes in Cassandra 6.0?

Not fully. Cassandra gives atomicity and isolation per partition, and lightweight transactions (IF conditions) give compare-and-set on a single partition. For Paxos-based LWT, the recommended production setup is paxos_variant v2 with paxos_state_purging set to repaired. Cassandra 6.0 adds Accord, which offers multi-partition, strict-serializable transactions through BEGIN TRANSACTION. Accord is beta and off by default, and 6.0 is still pre-GA (6.0-alpha3), so 5.0.9 remains the current GA release and you should not plan production designs on Accord yet.

Sources and further reading

• Apache Cassandra: Downloading Cassandra (Apache Cassandra project)
• Announcing Apache Cassandra® 5.0 (Apache Cassandra project)
• New Features in Apache Cassandra 5.0 (Apache Cassandra project)

The post Cassandra Best Practices: Data Modeling, Consistency, Operations first appeared on TheCodeBuzz.

Note- Version-specific facts are dated 2026-10-17.

The main principle is simple: use the smallest thing that works. A single call to an LLM with document lookup (retrieval) and a few examples is often enough. Agents trade latency and cost for flexibility. In simple terms, an LLM (large language model) is the text-generating AI behind chat assistants. In simple terms, an agentic workflow is a multi-step AI task in which a model uses tools and data while your code sets the steps, limits and checks. In simple terms, an agent is a system where the model itself decides the next step and which tool to use.

Next come the workflow-versus-agent choice, design patterns, the agent loop, durable execution, human approval, security with the OWASP Agentic Top 10, tracing, evaluation, and cost and latency.

Version note: As of 2026-10-17, this guide targets LangGraph 1.2.16, OpenAI Agents SDK 0.23.1, Microsoft Agent Framework 1.0, MCP specification revision 2026-07-28 and the OWASP Top 10 for Agentic Applications 2026.

 

In this guide

• In Plain English: What Is an Agentic Workflow?
• Agentic Workflow Best Practices at a Glance
• Agentic AI Workflow Architecture: Where It Fits in the Pipeline
• Agent Workflow vs Autonomous Agent: Choosing Patterns
• Build the Agent Loop: State, Limits, Durability and Approvals
• Secure Agentic Workflows with OWASP Agentic Top 10 Controls
• Observe, Evaluate and Tune Agents: Tracing, Evals, Cost and Latency
• Common Anti-Patterns in Agentic Workflows
• Production Readiness Checklist for AI Agents
• Glossary in Plain English
• Key Takeaways
• FAQ

What Is an Agentic Workflow?

Tip: what is an agentic workflow? Think of a capable assistant working through a to-do list. The assistant can look things up, use tools and check their own work, while a manager sets a time limit and a budget.

Tip: A human assistant who gets stuck usually notices. Here the “assistant” is software that writes likely-sounding answers, so it can be confidently wrong. That is why it needs checks a human assistant would not.

The assistant repeats one loop: think, do one thing, look at the result, then decide whether to continue, stop or ask a person. The animated diagram below shows this loop, including the step limit and the hand-off to a person.

These are the four terms you need for the rest of the article:

• Agentic workflow: In simple terms, a task where an AI repeats the think, act, check loop until the job is done.
• Agent: In simple terms, the AI part that chooses its own next step.
• LLM: In simple terms, a large language model, the program that reads and writes text.
• Tool call: In simple terms, the AI asking your code to run an action, such as a search or a database lookup.

Why it matters: without limits, state and checks, an agent can loop forever, spend money, or take a wrong action nobody notices.

Workflow or Agent: Who Decides the Steps?

The difference is who picks the path. In a workflow, your code decides the steps and the model fills them in. In an agent, the model decides the steps and the tools to use. This difference drives the agent workflow vs autonomous agent choice covered later.

Agentic Workflow Best Practices at a Glance

The rules below run in order from architecture decisions to day-to-day operations, so you can read the table top to bottom as a design sequence.

Four terms appear in the table. In simple terms, an idempotent call gives the same result when repeated. Least agency means giving an agent only the autonomy and permissions its task needs. Model tiering means using a small, cheap model for easy steps and a larger one for hard steps. A trajectory is the full sequence of steps and tool calls in one run.

Tip: an idempotent action is like a light switch marked “set to ON”. Pressing it twice leaves the light on. A toggle switch is not idempotent, because pressing it twice undoes the first press. This is why a retry is safe for one and risky for the other.

This table shows what to do and what to avoid in each area of an agentic workflow:

Each row is explained with its trade-off in the sections below.

Agentic AI Workflow Architecture: Where It Fits in the Pipeline

The agentic layer sits between retrieval and the user. It calls the knowledge built during ingestion, the tools and the LLM, while evaluation and operations wrap around the whole thing. The animated diagram below shows a document flowing into storage, then a user question driving the agent.

What does each pipeline stage do for the agent?

Each stage prepares something the agent uses at run time. Weak work early in the pipeline shows up later as poor agent decisions.

• Ingestion: loads and cleans source documents.
• Chunking: splits documents into pieces. In simple terms, a chunk is one small passage cut from a longer document.
• Embeddings: turn each chunk into numbers. In simple terms, an embedding is a list of numbers that places a text on a map of meaning.
• Vector store: keeps those embeddings searchable. In simple terms, a vector store is a database that finds texts by meaning instead of exact words.
• Retrieval: fetches the best-matching chunks for a question. In simple terms, retrieval is looking up the most relevant passages before answering.
• LLM: reads the prompt and writes text or picks a tool. It can only use what fits in its context window. In simple terms, the context window is the amount of text the model can read at once.
• Agent or workflow control: decides the next step, enforces limits and stores state.
• Evaluation and operations: record traces, budgets and alerts, and test behaviour.

Retrieval is one tool the agent can call, next to APIs and databases. If it returns the wrong chunks, every later step reasons from bad evidence.

Tip: Think of a research assistant with a library built in advance. The pipeline stocks and indexes the shelves. The agent decides when to visit them, which other tools to use, and when to stop. The analogy stops at one point: the assistant is a language model, so it can misread a good source with confidence.

Which orchestration approach should you choose?

Choose by failure semantics first: what happens on a crash, a timeout or bad tool output. Framework style comes second. The table below compares the four kinds of tooling, with facts dated 2026-10-17.

Pick the least autonomous architecture that meets the task. A short fixed chain does not need a framework. Pin exact versions in production, because LangGraph ships frequent patch releases and the OpenAI SDK is pre-1.0.

Agent Workflow vs Autonomous Agent: Choosing Patterns

Start with a single LLM call plus retrieval and examples. Move to a fixed workflow if that is not enough. Use an autonomous agent only when the steps cannot be known in advance.

Agentic systems usually trade latency and cost for better task performance, so each step up must earn its place. A study of production agents found that 16 of 20 case studies (80%) used predefined structured workflows, chosen for controllability and human oversight.

Tip: A workflow is a recipe card: the steps are written down and the cook follows them. An agent is a chef who decides the next step after tasting the dish. The analogy stops there: the chef here is a language model, so it can be confidently wrong and needs limits and checks.

Which design should you choose?

Apply these decision rules in order:

1. Steps known: use a fixed workflow, where your code decides the order.
2. Path depends on what the model finds: use an agent, but only if the task value justifies the extra cost and latency.
3. Mistake is costly or irreversible: add human approval gates before the risky action.

The animated diagram below walks a new task through these questions.

Which agentic workflow design patterns exist?

In simple terms, an orchestrator is a coordinator that splits a task and hands the parts to workers. This table compares the common agentic workflow design patterns.

When should you split into multiple agents?

Split only when roles need different tools, permissions or context. More agents multiply cost, latency and failure points, because every handoff is another place for a call to fail or for context to be lost. In multi-agent orchestration patterns, one agent with well-scoped tools is the default to beat.

Use Case: A retail returns-triage workflow routes each request to refund, exchange or fraud review. The categories are known, so a router plus fixed branches is enough, and refunds above a set amount wait for human approval.

Use Case: A finance research task uses orchestrator-workers. The orchestrator picks which filings and news to read based on the question, workers summarise each source, and an analyst reviews the draft before it is shared.

Build the Agent Loop: State, Limits, Durability and Approvals

An operable agent loop has an explicit state object (plan, observations, remaining budget), typed tool schemas, a retry policy, a loop limit, a per-step timeout, a cost budget and clear termination outcomes: succeeded, gave up or escalated. The CoreWeave production guide lists these as the minimum for knowing what an agent did and why it stopped. The same pieces are the base of production AI agents checklist items such as limits, retries and approvals.

Tip: Think of a contractor with a work order: a task list, a spending cap, a deadline and a rule to phone the client before any big purchase. The analogy stops at trust. A language model can be confidently wrong, so your code enforces the cap, the deadline and the phone call. It does not rely on the model to respect them.

The animated diagram below shows one pass of the loop, the state card that changes on every pass, and the three ways the loop can end.

Which terms does the loop use?

• Agent state: In simple terms, it is the notebook the agent carries between steps: the goal, the plan, what it has seen and how much budget is left.
• Token: In simple terms, it is a small piece of text (a word or part of a word) that models read and write. Cost is usually counted in tokens.
• Temperature: In simple terms, it is a setting for how adventurous the model’s word choices are. Set it low for tool selection, because you want the same situation to give the same tool and well-formed arguments, not creative variation.
• Idempotency: In simple terms, doing the same action twice has the same effect as doing it once. Reading an order is idempotent. Charging a card is not, unless you send an idempotency key the payment service can recognise.
• Checkpoint: In simple terms, it is a saved copy of the state after a step, like a game save, so a crash resumes instead of restarting.
• Superstep: In simple terms, it is one round of a graph-based framework in which the ready steps run and the state is saved. LangGraph uses this term.

How do you set loop limits and budgets?

The research gives no universal numbers for step limits, timeouts or cost caps, so treat every default as a placeholder to be tuned. Replay a set of real tasks and record the step-count distribution and the cost per successful run. Set the loop limit slightly above a high percentile of successful runs, then review every run that hits it. Those runs show whether the limit is too tight or the agent is genuinely stuck.

How do you make the loop survive failures?

Checkpoint after every step. Retry only idempotent calls, or writes that carry an idempotency key. Classify each error before deciding what to do:

Send exhausted tasks, with their saved state, to a dead-letter queue. In simple terms, that is a holding tray for jobs that failed, kept so a person can inspect and replay them. LangGraph’s graceful shutdown stops a run after the current superstep and saves a resumable checkpoint. Its checkpoint backends are in-memory or SQLite for development and PostgreSQL for production.

How do you add human approval?

For human-in-the-loop AI agents, interrupt before risky tools such as payments, deletes and outbound emails. Show the proposed arguments, then resume on approve or edit. Gate by risk level only, because approval fatigue is real: reviewers who see every action start approving without reading.

Python example: a bounded agent loop

Here’s a simplified example using the standard library and pydantic v2. The call_llm function is a stub you replace, and you can add custom logic for planning, logging and storage.

Python

import time
import uuid
from dataclasses import dataclass, field
from enum import Enum
from typing import Any, Callable

from pydantic import BaseModel, Field, ValidationError


class Outcome(Enum):
    SUCCEEDED = "succeeded"
    GAVE_UP = "gave_up"
    ESCALATED = "escalated"


@dataclass
class AgentState:
    goal: str
    run_id: str = field(default_factory=lambda: uuid.uuid4().hex)
    plan: list[str] = field(default_factory=list)
    observations: list[str] = field(default_factory=list)
    step: int = 0
    tokens_used: int = 0
    cost_usd: float = 0.0
    answer: str | None = None


class Decision(BaseModel):
    action: str  # "tool" or "finish"
    tool: str | None = None
    args: dict[str, Any] = Field(default_factory=dict)
    answer: str | None = None
    tokens: int = 0
    cost_usd: float = 0.0


class RefundArgs(BaseModel):
    order_id: str = Field(pattern=r"^ORD-\d{6}$")
    amount: float = Field(gt=0, le=500)


def issue_refund(args: RefundArgs, idempotency_key: str) -> str:
    # Replace: send idempotency_key to the payment API so a retry cannot pay twice.
    return f"refund of {args.amount} queued for {args.order_id}"


@dataclass
class Tool:
    args_model: type[BaseModel]
    func: Callable[[Any, str], str]
    risky: bool = False
    idempotent: bool = False  # True = read-only, or a write that uses the key


RETRYABLE = (TimeoutError, ConnectionError)


def call_llm(state: AgentState) -> Decision:
    # Stub: call your model here (low temperature) and return a Decision.
    raise NotImplementedError


def call_tool(tool: Tool, args: BaseModel, key: str, retries: int, deadline: float) -> str:
    attempts = retries + 1 if tool.idempotent else 1
    for attempt in range(attempts):
        try:
            return tool.func(args, key)
        except RETRYABLE:
            if attempt == attempts - 1 or time.monotonic() >= deadline:
                raise
            time.sleep(min(0.5 * 2**attempt, 5))
    raise RuntimeError("unreachable")


def run_agent(
    state: AgentState,
    tools: dict[str, Tool],
    approve: Callable[[str, BaseModel], BaseModel | None],
    save_checkpoint: Callable[[AgentState], None],
    *,
    max_steps: int = 8,         # placeholders: tune from replayed real tasks
    max_cost_usd: float = 0.50,
    timeout_s: float = 60.0,
    max_retries: int = 2,
) -> Outcome:
    deadline = time.monotonic() + timeout_s
    while (state.step < max_steps and state.cost_usd < max_cost_usd
           and time.monotonic() < deadline):
        decision = call_llm(state)
        state.step += 1
        state.tokens_used += decision.tokens
        state.cost_usd += decision.cost_usd

        if decision.action == "finish":
            state.answer = decision.answer
            save_checkpoint(state)
            return Outcome.SUCCEEDED

        tool = tools.get(decision.tool or "")
        if tool is None:
            state.observations.append(f"unknown tool: {decision.tool}")
        else:
            try:
                args = tool.args_model.model_validate(decision.args)
            except ValidationError as exc:
                state.observations.append(f"invalid arguments: {exc}")
            else:
                if tool.risky:
                    args = approve(decision.tool, args)  # approve, edit or decline
                    if args is None:
                        save_checkpoint(state)
                        return Outcome.ESCALATED
                key = f"{state.run_id}-{state.step}"  # stable across retries
                try:
                    state.observations.append(
                        call_tool(tool, args, key, max_retries, deadline))
                except PermissionError:
                    save_checkpoint(state)
                    return Outcome.ESCALATED
                except Exception as exc:  # fatal or retries exhausted
                    state.observations.append(f"tool failed: {exc}")
                    save_checkpoint(state)
                    return Outcome.GAVE_UP
        save_checkpoint(state)  # checkpoint after every step

    save_checkpoint(state)  # caller pushes this state to the dead-letter queue
    return Outcome.GAVE_UP

run_agent returns an Outcome (SUCCEEDED, GAVE_UP or ESCALATED) and saves the state before every return, so a person or a replay job can pick up from the last step.

One limit to know: the loop checks the deadline between steps, so each tool function must enforce its own per-step timeout.

How does this map to agent frameworks?

The same loop appears in LangGraph, the OpenAI Agents SDK and Microsoft Agent Framework under different names. Your state object becomes the framework’s state or session, the checkpoint function becomes its persistence layer, and the approval callback becomes an interrupt or approval hook. Check each framework’s documentation for exact signatures. Pin versions, because the OpenAI SDK is still 0.x (0.23.1 on Oct 2, 2026) and LangGraph ships frequent patch releases (1.2.16 on Oct 16, 2026).

Secure Agentic Workflows with OWASP Agentic Top 10 Controls

Apply least agency. An agent gets only the autonomy, tools and credentials the task needs, and it earns more only after evaluation. Use the OWASP Top 10 for Agentic Applications 2026 (released Dec 9, 2025, ASI01 to ASI10) as your review checklist.

Tip: Think of a temp worker given a key card that opens only the rooms needed today, and that stops working tonight. Unlike a human temp, an agent can be tricked by a sentence hidden in a document it reads. So the key card limits matter even more.

Which OWASP agentic risks should you check?

Here are the ten risks in their published order, each with a typical symptom and a control.

In simple terms, a sandbox is a locked room where code can run without touching your real systems.

How do MCP tool servers change the security picture?

As of 2026-10-17, the current MCP revision is 2026-07-28 (the previous final one is 2025-11-25). In simple terms, MCP (Model Context Protocol) is a standard way for agents to discover and call tools on a server.

The new revision is stateless. The initialize handshake and the Mcp-Session-Id header are gone. Each request now carries its protocol version, client identity and capabilities in _meta. The revision also adds Multi Round-Trip Requests, header-based routing, cacheable list results, hardened authorization and an extensions framework.

• Scale freely: servers can sit behind a load balancer without sticky sessions.
• Keep state out of the server: hold per-session data in your agent state, where you can checkpoint and audit it.
• Test before migrating: the C# SDK v2.0 implements this spec, but the Python, TypeScript, Go and C# SDKs are in beta.

Use Case: A healthcare scheduling agent gets a read-only calendar tool to find open slots. A separate booking tool sits behind human approval, which shows the patient, slot and clinician. Its credential is valid only for that task. Every call lands in the audit log.

Observe, Evaluate and Tune Agents: Tracing, Evals, Cost and Latency

Trace every run as one tree, evaluate whole trajectories (the full sequence of steps, not just the final answer), and set your limits and model tiers from that data. This is the core of AI agent observability and guardrails.

How do you trace an agent run?

Record each run as one trace with a span per step. In simple terms, a span is a timed record of one action, and a trace is the tree of spans for one run. OpenTelemetry is an open standard for producing and exporting this data. Its GenAI conventions put an invoke_agent span at the top, with chat spans for model calls and execute_tool spans for tool calls beneath it.

Tip: A trace is like a receipt that lists every task the assistant did, in order, with the time each took. Unlike a receipt, it can also show which step failed and why.

The animated diagram below builds this tree step by step for a refund agent and sends the finished trace to the eval suite and alerts.

Per step, record tokens, cost, latency, retry count and the final termination outcome. Prompt and response content is opt-in, because it can contain personal data. The spec is still marked Development, so attribute names can change. Keep them in one helper.

C#

using System.Diagnostics;

// Simplified helper. Attribute names may change while the GenAI spec is in Development.
public static class AgentTrace
{
    private static readonly ActivitySource Source = new("TheCodeBuzz.Agents");

    public static Task<T> AgentAsync<T>(string agent, Func<Task<T>> body) =>
        Run($"invoke_agent {agent}", "invoke_agent", "gen_ai.agent.name", agent, body);

    public static Task<T> ChatAsync<T>(string model, Func<Task<T>> body) =>
        Run($"chat {model}", "chat", "gen_ai.request.model", model, body);

    public static Task<T> ToolAsync<T>(string tool, Func<Task<T>> body) =>
        Run($"execute_tool {tool}", "execute_tool", "gen_ai.tool.name", tool, body);

    public static void RecordUsage(int inputTokens, int outputTokens)
    {
        Activity.Current?.SetTag("gen_ai.usage.input_tokens", inputTokens);
        Activity.Current?.SetTag("gen_ai.usage.output_tokens", outputTokens);
    }

    private static async Task<T> Run<T>(string name, string operation,
        string key, string value, Func<Task<T>> body)
    {
        using var activity = Source.StartActivity(name);
        activity?.SetTag("gen_ai.operation.name", operation);
        activity?.SetTag(key, value);
        try
        {
            return await body();
        }
        catch (Exception ex)
        {
            activity?.SetStatus(ActivityStatusCode.Error, ex.Message);
            activity?.SetTag("error.type", ex.GetType().FullName);
            throw;
        }
    }
}

Nested calls become child spans automatically, because Activity.Current flows through async code. Register the source with AddSource("TheCodeBuzz.Agents") in OpenTelemetry for .NET, otherwise StartActivity returns null and nothing is exported.

How do you evaluate an agent?

Build a regression suite from real tasks and score the trajectory, not only the answer. A trajectory evaluation checks the path the agent took. A regression suite is a fixed set of tests you rerun after every change.

• Trajectory checks: right tool, right arguments, no forbidden calls, step count and cost.
• Answer quality: score the final output separately.
• Rerun on any change: prompt, tool schema or model, because they interact.
• Adversarial cases: include prompt injection hidden in tool output.
• Two environments: keep offline evals apart from sampled production evals.

How do you control cost and latency?

Pick the controls below and check each against your eval suite. Every one trades something for speed or savings.

To tune tiers, plot cost per successful task against success rate for each tier. Choose the knee of the curve, where extra spend stops buying much accuracy.

Which alerts should you set?

Alert on loop-limit hits, escalation rate, cost per run and tool error rate. Review every run that hits a limit, since that shows whether the limit or the task design is wrong. These signals also belong on any production AI agents checklist.

Common Anti-Patterns in Agentic Workflows

Most failures in production AI agents come from a small set of repeated design mistakes. The table below lists nine of them with the symptom you will see and the fix.

Tip: An anti-pattern is a habit that looks sensible at first and causes trouble later, like a manager who gives a new assistant the master key, no deadline and no instructions to report back. The analogy stops at one point: a human assistant would usually push back, while a language model will keep going.

Which Agentic Workflow Mistakes Should You Avoid?

Use this table as a review list for agentic AI workflow architecture and for any production AI agents checklist.

For multi-agent orchestration patterns, human-in-the-loop AI agents and AI agent observability and guardrails, see the sections that cover each in detail.

Production Readiness Checklist for AI Agents

Use this production AI agents checklist before you release an agent to real users. It runs from design to operations. Every item can be verified with a test, a config value or a dashboard.

Tip: Think of the pre-flight checklist a pilot runs before takeoff. Each line is a quick, checkable fact, not an opinion. The analogy stops in one place: an agent’s checklist must be run again whenever the prompt, a tool or the model changes.

Work through these items in order:

1. Architecture choice: Write down why a single LLM call or fixed workflow is not enough. If you can’t, don’t build an agent.
2. Outcomes: Define succeeded, gave up and escalated, plus the conditions that end a run.
3. Tools: Give every tool a typed schema. Validate arguments before the tool runs.
4. State: Keep an explicit state object and checkpoint after every step.
5. Limits: Set step, time and cost limits from replayed eval data, not guesses.
6. Retries: Retry only idempotent calls. Send exhausted tasks to a dead-letter queue with their saved state.
7. Approvals: Add human-in-the-loop AI agent gates on payments, deletes and outbound messages.
8. Least agency: Use short-lived, task-scoped credentials and sandboxed code, mapped to each OWASP agentic risk.
9. Tracing: Trace each run as one tree. Keep prompt and response capture off by default.
10. Regression suite: Run trajectory evals in CI on every prompt, schema or model change, including prompt injection cases that arrive through tool output.
11. Versions: Pin dependencies and record the MCP spec version you tested against.
12. Operations: Set alerts for loop-limit hits, escalation rate, cost per run and tool errors. Rehearse the kill switch and the rollback plan before you need them.

Glossary in Plain English

This glossary lists the terms used in this article on agentic AI workflow architecture, grouped by topic. Each analogy comes with a note where it stops being accurate.

In plain English: Treat the analogies as a phrasebook, not a specification. They help you picture an idea, and the third column says where each picture stops matching the real thing.

Models and Cost Terms

These terms describe the model and what it costs to run.

Knowledge and Retrieval Terms

These terms cover how knowledge gets to the agent.

Loop and Reliability Terms

These terms describe how the loop keeps running and recovers from failure.

Security and Observability Terms

These terms cover protection, monitoring and testing.

Key Takeaways

These are the points to keep from the article, ordered from design decisions to operations.

• Start with the simplest design: try a single LLM call with retrieval and examples first, then a fixed workflow. Use an autonomous agent only when the steps cannot be known in advance, because agents usually cost more in latency and money.
• Workflows dominate production: in the study cited earlier, 16 of 20 case studies (80%) used predefined structured workflows for control and human oversight. If code can decide the steps, let code decide them.
• Make the loop explicit and bounded: keep an explicit state object, typed and validated tool schemas, and limits for steps, time and cost. Return a clear outcome (succeeded, gave up or escalated). Set the limits from replayed real tasks, not from a universal number.
• Design for crashes and retries: checkpoint after every step, retry only idempotent calls (or use idempotency keys for writes), and send exhausted tasks to a dead-letter queue with the saved state. Choose tooling by failure semantics before framework style.
• Apply least agency and the OWASP list: give agents short-lived, task-scoped credentials and scoped tools. Treat retrieved content and tool output as untrusted data, sandbox code execution, and gate risky actions by risk level. Keep a kill switch and audit logs.
• Trace and evaluate trajectories: record each run as one trace tree and score the tools, arguments, step count and cost, not only the final answer. Re-run the regression suite whenever the prompt, tool schema or model changes.
• Pin versions and re-check dated facts: LangGraph patch releases are frequent, the OpenAI Agents SDK is still 0.x, and the OpenTelemetry GenAI conventions are still in Development. Record the MCP spec revision you target, and re-verify the version facts dated 2026-10-17 before you rely on them.

That’s all! Happy coding!

Did this solve your problem? Please share your questions or experience in the comments below. Bookmark this page or share it with your team, and subscribe to TheCodeBuzz for more AI engineering best practices.

FAQ

What is an agentic workflow and how is it different from an AI agent?

An agentic workflow is a process where code sets the steps and a language model does the work inside them (e.g. classify, look up, draft). An AI agent is different because the model itself decides which step or tool comes next. Most production systems use workflows for this reason, since a fixed path is easier to test, limit and audit. Many real systems mix both, with a fixed outer flow and one agent loop for a single open-ended step.

When should I use a fixed workflow instead of an autonomous agent?

Use a fixed workflow whenever you can write down the steps before the task starts. Start with a single model call plus retrieval and examples, move to a workflow if that is not enough, and use an agent only when the path depends on what the model finds along the way. Agents usually cost more and respond more slowly, so the task value must justify that. If a wrong action is expensive, add an approval gate whichever design you pick.

How do I control cost and latency in an agent loop?

Set hard limits first: a maximum step count, a per-step timeout, a deadline and a token or cost budget per run. Then reduce spend with model tiering (a small model for routing and extraction, a larger one for hard planning), caching of stable prompt prefixes, summarising old steps, and parallel calls for independent tools. Summarising can drop detail, so check it against your regression suite. Tune the numbers from real traces by comparing cost per successful task with success rate for each tier.

How do I add human-in-the-loop approval to an agent?

Pause the loop before any risky tool call, such as a payment, a delete or an outbound email, and show the reviewer the exact proposed arguments. Save the agent state at that point so the run can resume after the person approves, edits or rejects the action. Frameworks such as LangGraph offer interrupts for this, and the same idea works in plain code with an approval callback. Gate by risk level only, because asking for approval on every step leads to reviewers clicking through without reading.

What are the biggest security risks for agentic applications, and how do I reduce them?

The OWASP Top 10 for Agentic Applications 2026 is the best checklist, and its risks include agent goal hijack, tool misuse, identity and privilege abuse, and memory and context poisoning. The guiding rule is least agency: give the agent only the autonomy and access it has earned. In practice, use short-lived credentials scoped to the task, validate tool parameters, run generated code in a sandbox, and treat retrieved content and tool output as untrusted data, never as instructions. Add approval for sensitive actions, audit logs and a kill switch.

Sources and further reading

• Building Effective AI Agents (Anthropic Engineering)
• Measuring Agents in Production (arXiv)
• Agentic workflows in production: Mechanisms, costs and trade-offs (CoreWeave)
• OWASP Top 10 for Agentic Applications – The Benchmark for Agentic Security in the Age of Autonomous AI (OWASP Gen AI Security Project)
• Lessons from OWASP Top 10 for Agentic Applications (Auth0)
• langgraph · PyPI (PyPI)
• LangGraph 1.0 and 1.2 in 2026: Why Durable State Has Changed Everything for Python Agent Developers (JBI Training)
• Releases · openai/openai-agents-python (GitHub (OpenAI))
• Changelog (OpenAI)
• Microsoft Ships Production-Ready Agent Framework 1.0 for .NET and Python (Visual Studio Magazine)

Please share this article with your friends and Subscribe to the blog to get a notification on freshly published best practices of software development.

The post Agentic Workflow Best Practices: Architecture and Checklist first appeared on TheCodeBuzz.