<!-- mobian-agent-page publisher="dailydev" canonical="https://daily.dev/posts/what-is-a-data-topology-planetscale-8ttupi03l" -->

---
title: What is a data topology? — PlanetScale | daily.dev
description: PlanetScale explains the concept of a 'data topology' in Neki, its PostgreSQL sharding system inspired by Vitess. A data topology is a JSON configuration...
canonical: https://daily.dev/posts/what-is-a-data-topology-planetscale-8ttupi03l
twitter:card: summary_large_image
twitter:site: @dailydotdev
og:type: website
og:site_name: daily.dev
og:title: What is a data topology? — PlanetScale | daily.dev
og:description: PlanetScale explains the concept of a 'data topology' in Neki, its PostgreSQL sharding system inspired by Vitess. A data topology is a JSON configuration...
og:url: https://daily.dev/posts/what-is-a-data-topology-planetscale-8ttupi03l
og:image: https://api.daily.dev/og/posts/8TTUpI03l.png
og:image:alt: What is a data topology? — PlanetScale
og:image:width: 1200
og:image:height: 630
og:locale: en
---

> ## Documentation Index
> Fetch the complete documentation index at: https://daily.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# What is a data topology? — PlanetScale

**[PlanetScale](https://daily.dev/sources/planetscale)** · 5 min read · 0 upvotes · 0 comments

## Summary

PlanetScale explains the concept of a 'data topology' in Neki, its PostgreSQL sharding system inspired by Vitess. A data topology is a JSON configuration mapping logical PostgreSQL tables to physical shards, composed of three building blocks: shard indexes (hash, modulo, or range-based routing key transformations), shard groups (physical shard sets with assigned key ranges), and databases (binding tables to shard groups following PostgreSQL's database/schema/table hierarchy). A worked example shows how a customer_id column routes to different shards depending on the strategy used, and how unlisted tables inherit default shard groups from their schema, database, or cluster.

## Full article

daily.dev links to this article rather than hosting it. Read it at the original source: <https://planetscale.com/blog/what-is-a-data-topology>

## Questions this post answers

### How does PlanetScale's Neki route queries to the correct PostgreSQL shard?

Neki uses a JSON configuration called a data topology that maps logical PostgreSQL tables to physical shards. It defines shard indexes (the column and transformation used to compute a routing key), shard groups (physical shards with assigned key ranges), and databases (which bind tables to shard groups following the PostgreSQL database, schema, and table hierarchy).

_Teams designing sharded PostgreSQL architectures can compare routing approaches like this one via daily.dev._

### What are the differences between hash-based, modulo-based, and range-based shard indexes in Neki?

Hash-based indexes use xxhash to map a value into the routing space, modulo-based indexes divide an integer by a configured modulus and use the remainder, and range-based indexes use the integer value directly without hashing. Each strategy transforms the same shard key value, such as a customer_id, into a different routing key, which can send the same row to a different physical shard depending on the strategy chosen.

_Engineers evaluating sharding key strategies often track deep dives like this on daily.dev._

### Do all tables need to be listed explicitly in a PostgreSQL sharding configuration?

No, most tables do not need to appear explicitly in a data topology. An unlisted table inherits a default shard group from its schema, then its database, then the cluster, which lets a single default shard an entire database while only exceptions are listed individually.

_Anyone planning a sharded schema can weigh defaults-versus-exceptions tradeoffs surfaced on daily.dev._

## Similar posts on daily.dev

- [Making 768 servers look like 1 — PlanetScale](https://daily.dev/posts/making-768-servers-look-like-1-planetscale-2dvlb3eoz) · Hacker News · 0 upvotes · 0 comments
- [Database Sharding: How It Works and When You Actually Need It](https://daily.dev/posts/database-sharding-how-it-works-and-when-you-actually-need-it-wbf2g1gif) · Last9 · 1 upvotes · 0 comments
- [An Intro to DB Sharding](https://daily.dev/posts/an-intro-to-db-sharding-gphrjfgug) · System Design Codex · 12 upvotes · 0 comments
- [Data Sharding vs Data Partitioning: A Complete Guide for High-Performance Databases](https://daily.dev/posts/data-sharding-vs-data-partitioning-a-complete-guide-for-high-performance-databases-yufjm8g14) · C\# Corner · 1 upvotes · 0 comments

---

Tags: [#postgresql](https://daily.dev/tags/postgresql), [#planetscale](https://daily.dev/tags/planetscale)

[View this post on daily.dev](https://daily.dev/posts/what-is-a-data-topology-planetscale-8ttupi03l)

```json
{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://daily.dev/#organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180},"sameAs":["https://twitter.com/dailydotdev","https://github.com/dailydotdev","https://www.linkedin.com/company/daily-dev-ltd"]},{"@type":"WebSite","@id":"https://daily.dev/#website","url":"https://daily.dev","name":"daily.dev","publisher":{"@id":"https://daily.dev/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://daily.dev/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]}
{"@context":"https://schema.org","@type":"TechArticle","headline":"What is a data topology? — PlanetScale","url":"https://daily.dev/posts/what-is-a-data-topology-planetscale-8ttupi03l","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/what-is-a-data-topology-planetscale-8ttupi03l"},"datePublished":"2026-09-10T14:53:19.214Z","dateModified":"2026-10-15T02:22:12.320Z","description":"PlanetScale explains the concept of a 'data topology' in Neki, its PostgreSQL sharding system inspired by Vitess. A data topology is a JSON configuration...","image":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/7a3d4efa7c5a6f4c14fa2cd58e418385?_a=AQAEuop","thumbnailUrl":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/7a3d4efa7c5a6f4c14fa2cd58e418385?_a=AQAEuop","isAccessibleForFree":true,"articleSection":"PlanetScale","inLanguage":"en","publisher":{"@type":"Organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180}},"author":{"@type":"Organization","name":"PlanetScale","logo":"https://media.daily.dev/image/upload/t_logo,f_auto/v1/logos/09515c29cafc45618b3f117eab4fccf8","url":"https://daily.dev/squads/planetscale"},"commentCount":0,"discussionUrl":"https://daily.dev/posts/what-is-a-data-topology-planetscale-8ttupi03l","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":0},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":0}],"keywords":"postgresql,planetscale","timeRequired":"PT5M"}
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"PlanetScale","item":"https://daily.dev/squads/planetscale"},{"@type":"ListItem","position":3,"name":"What is a data topology? — PlanetScale"}]}
{"@context":"https://schema.org","@type":"FAQPage","@id":"https://daily.dev/posts/what-is-a-data-topology-planetscale-8ttupi03l#faq","mainEntity":[{"@type":"Question","name":"How does PlanetScale's Neki route queries to the correct PostgreSQL shard?","acceptedAnswer":{"@type":"Answer","text":"Neki uses a JSON configuration called a data topology that maps logical PostgreSQL tables to physical shards. It defines shard indexes (the column and transformation used to compute a routing key), shard groups (physical shards with assigned key ranges), and databases (which bind tables to shard groups following the PostgreSQL database, schema, and table hierarchy). Teams designing sharded PostgreSQL architectures can compare routing approaches like this one via daily.dev."}},{"@type":"Question","name":"What are the differences between hash-based, modulo-based, and range-based shard indexes in Neki?","acceptedAnswer":{"@type":"Answer","text":"Hash-based indexes use xxhash to map a value into the routing space, modulo-based indexes divide an integer by a configured modulus and use the remainder, and range-based indexes use the integer value directly without hashing. Each strategy transforms the same shard key value, such as a customer_id, into a different routing key, which can send the same row to a different physical shard depending on the strategy chosen. Engineers evaluating sharding key strategies often track deep dives like this on daily.dev."}},{"@type":"Question","name":"Do all tables need to be listed explicitly in a PostgreSQL sharding configuration?","acceptedAnswer":{"@type":"Answer","text":"No, most tables do not need to appear explicitly in a data topology. An unlisted table inherits a default shard group from its schema, then its database, then the cluster, which lets a single default shard an entire database while only exceptions are listed individually. Anyone planning a sharded schema can weigh defaults-versus-exceptions tradeoffs surfaced on daily.dev."}}]}
```

