{"id":"design-sales-rank","title":"Design Amazon's sales rank by category","sections":[{"id":"overview","title":"Overview","html":"<p>Open a product page on a large online store and you will often see a line such as \"#3 in Kitchen Scales\". Browse a category and you can sort it by \"Best Sellers\". Both come from a <strong>sales rank</strong>: for each category, a list of products ordered by how many units sold recently. This chapter designs the service that computes those lists and the API that serves them.</p>\n<p>The two halves of the problem pull in opposite directions. Computing the rank means reading every sale from the past week, about a quarter of a billion records, and adding them up by category and product: a large, slow, offline job. Serving the rank means answering tens of thousands of requests a second for the same few lists: a small, fast lookup. The design keeps the two apart. A batch job does the heavy counting once an hour, and the read path only looks up the job's last answer.</p>\n<p>Amazon describes its own version, Best Sellers Rank, in a short help page. The page says the calculation \"is based on Amazon sales, and is updated frequently to reflect recent and historical sales of every item sold on Amazon\". It also says Amazon created category and subcategory lists because the overall list \"doesn't always indicate how well an item is selling in relation to similar items\", and that a product page shows the item's rank in a few popular subcategories where it ranks high. The UK and Canadian versions of the same page say the calculation is updated hourly. The page doesn't give a formula, so this chapter designs a simpler rule of its own: units sold in the past seven days.</p>\n<p>The chapter follows the four steps from <a href=\"/learn/system-design-interview\">The system design interview, step by step</a>.</p>","headings":[]},{"id":"step-1-outline-use-cases-constraints-and-assumptions","title":"Step 1: Outline use cases, constraints and assumptions","html":"<h3 id=\"step-1-outline-use-cases-constraints-and-assumptions\">Step 1: Outline use cases, constraints and assumptions</h3>\n<h4 id=\"use-cases\">Use cases</h4>\n<p>We'll scope the problem to these use cases:</p>\n<ul>\n<li><strong>The service calculates the past week's most popular products in each category.</strong> \"Most popular\" means the most units sold.</li>\n<li><strong>A user views the past week's most popular products in a category.</strong> For example, the top 20 sellers in \"Kitchen Scales\".</li>\n<li><strong>The service is highly available.</strong> If the ranking job fails or a database goes down, users still see a ranking, even if it's an hour or two old.</li>\n</ul>\n<h4 id=\"out-of-scope\">Out of scope</h4>\n<ul>\n<li>The rest of the store: the catalog, search, the cart, checkout and payments. We only design the parts that compute and serve the sales rank.</li>\n<li>How sales are recorded in the first place. We assume the checkout system calls a <strong>Sales API</strong> for every completed sale, and that this API writes a log line we can read later.</li>\n</ul>\n<h4 id=\"assumptions\">Assumptions</h4>\n<p>These numbers are inputs for the exercise. They aren't figures from Amazon.</p>\n<ul>\n<li>Traffic is not evenly distributed. Some categories and some hours are much busier than others.</li>\n<li>A product can be in several categories. A kitchen scale might be in \"Kitchen Scales\" and in \"Baking Tools\".</li>\n<li>A product never changes category.</li>\n<li>Categories are flat. There are no subcategories such as <code>home/kitchen/scales</code>.</li>\n<li>Rankings must be refreshed at least once an hour. The most popular products might need refreshing more often.</li>\n<li>There are 10 million products and 1,000 categories.</li>\n<li>There are 1 billion sales transactions a month.</li>\n<li>There are 100 billion read requests a month for rankings, so reads outnumber transactions 100 to 1.</li>\n</ul>\n<h4 id=\"calculate-usage\">Calculate usage</h4>\n<p><strong>Size of one transaction.</strong> Each sale record holds:</p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n<div class=\"table-wrap\"><table><thead><tr><th>Field</th><th>Size</th></tr></thead><tbody><tr><td><code>created_at</code> (timestamp)</td><td>5 bytes</td></tr><tr><td><code>product_id</code></td><td>8 bytes</td></tr><tr><td><code>category_id</code></td><td>4 bytes</td></tr><tr><td><code>seller_id</code></td><td>8 bytes</td></tr><tr><td><code>buyer_id</code></td><td>8 bytes</td></tr><tr><td><code>quantity</code></td><td>4 bytes</td></tr><tr><td><code>total_price</code></td><td>5 bytes</td></tr><tr><td><strong>Total</strong></td><td><strong>42 bytes, call it about 40</strong></td></tr></tbody></table></div>\n<p><strong>Storage.</strong></p>\n<ul>\n<li>New sales data per month: 1 billion × 42 bytes = 42 GB, or about 40 GB.</li>\n<li>Over three years: 42 GB × 36 months = 1,512 GB, about 1.5 TB.</li>\n<li>Almost all of this is new records. Sales are appended to a log and never updated in place.</li>\n</ul>\n<p><strong>Request rates.</strong> A 30-day month has 30 × 86,400 = 2,592,000 seconds, about 2.6 million. So 1 request a second is about 2.6 million requests a month.</p>\n<ul>\n<li>Transactions: 1,000,000,000 ÷ 2,592,000 ≈ 386 a second, about <strong>400 a second</strong> on average. Traffic is uneven, so assume a peak of three times that, about <strong>1,200 a second</strong>.</li>\n<li>Reads: 100,000,000,000 ÷ 2,592,000 ≈ 38,600 a second, about <strong>40,000 a second</strong> on average and about <strong>120,000 a second</strong> at a 3× peak.</li>\n</ul>\n<p><strong>Input to one ranking run.</strong> A week is 7 ÷ 30 of a month:</p>\n<ul>\n<li>1 billion × 7 ÷ 30 ≈ 233 million transactions in the window.</li>\n<li>233 million × 42 bytes ≈ 9.8 GB, about <strong>10 GB</strong> of input per run.</li>\n<li>One hour of sales is 1 billion ÷ (30 × 24) ≈ 1.4 million transactions, about 58 MB.</li>\n</ul>\n<p><strong>Size of the result.</strong> The output has at most one row per (category, product) pair that sold something in the week. Assume each product is in two categories on average. Then there are at most 10 million × 2 = 20 million rows. Budget 100 bytes a row, including indexes and per-row overhead, and the whole table is 20 million × 100 bytes = <strong>2 GB</strong>. If we keep only the top 100 products in each category, it's 1,000 × 100 = 100,000 rows, about <strong>10 MB</strong>.</p>\n<p><strong>Read bandwidth.</strong> Assume a response holds 20 products and is about 2 KB of JSON. Then 40,000 × 2 KB = 80 MB a second on average, and 240 MB a second at peak.</p>\n<p><strong>What these numbers tell us.</strong></p>\n<ul>\n<li>Reads dominate, and they all ask for one of only 1,000 lists. The answers fit in a few megabytes of memory. That's a perfect fit for a cache, and even for a CDN.</li>\n<li>Writes are simple appends at a few hundred a second. They don't need a database on the hot path; a log in cheap storage is enough.</li>\n<li>The ranking itself is a batch computation over about 10 GB, repeated every hour. That's modest for a small cluster, but it's a full re-read of data that has mostly been read before. We'll look at doing it incrementally.</li>\n<li>Three years of raw sales, about 1.5 TB, is too much to keep in the database that serves reads, but trivial for an object store.</li>\n</ul>\n<p>The <a href=\"/learn/estimation\">estimation</a> chapter explains this kind of arithmetic in more detail.</p>","headings":[{"id":"step-1-outline-use-cases-constraints-and-assumptions","title":"Step 1: Outline use cases, constraints and assumptions","depth":3},{"id":"use-cases","title":"Use cases","depth":4},{"id":"out-of-scope","title":"Out of scope","depth":4},{"id":"assumptions","title":"Assumptions","depth":4},{"id":"calculate-usage","title":"Calculate usage","depth":4}]},{"id":"step-2-create-a-high-level-design","title":"Step 2: Create a high-level design","html":"<h3 id=\"step-2-create-a-high-level-design\">Step 2: Create a high-level design</h3>\n<figure class=\"diagram\" data-text=\"Client -> Web server (reverse proxy); Web server (reverse proxy) -> Read API; Web server (reverse proxy) -> Sales API; Read API -> SQL database (sales_rank) (top products); Sales API -> Object store (sales logs) (append log); Object store (sales logs) -> Sales Rank Service (hourly job); Sales Rank Service -> SQL database (sales_rank) (load results)\"><div class=\"diagram-scroll\"><svg class=\"dg\" viewBox=\"0 0 800 325\" width=\"800\" role=\"img\" aria-label=\"Sales rank: the first design\"><defs><marker id=\"dg-arrow\" viewBox=\"0 0 10 10\" refX=\"9\" refY=\"5\" markerWidth=\"7\" markerHeight=\"7\" orient=\"auto-start-reverse\"><path class=\"dg-arrowhead\" d=\"M0,1 L9,5 L0,9 z\"></path></marker></defs><line class=\"dg-edge\" x1=\"151\" y1=\"162\" x2=\"167\" y2=\"162\" marker-end=\"url(#dg-arrow)\"></line><line class=\"dg-edge\" x1=\"278.7\" y1=\"133\" x2=\"361.3\" y2=\"71\" marker-end=\"url(#dg-arrow)\"></line><line class=\"dg-edge\" x1=\"278.7\" y1=\"191\" x2=\"361.3\" y2=\"253\" marker-end=\"url(#dg-arrow)\"></line><line class=\"dg-edge\" x1=\"471\" y1=\"42\" x2=\"647\" y2=\"42\" marker-end=\"url(#dg-arrow)\"></line><line class=\"dg-edge\" x1=\"471\" y1=\"282\" x2=\"647\" y2=\"282\" marker-end=\"url(#dg-arrow)\"></line><line class=\"dg-edge\" x1=\"674.7\" y1=\"248\" x2=\"601.3\" y2=\"193\" marker-end=\"url(#dg-arrow)\"></line><line class=\"dg-edge\" x1=\"598.7\" y1=\"133\" x2=\"672\" y2=\"78\" marker-end=\"url(#dg-arrow)\"></line><rect class=\"dg-node dg-client\" x=\"12\" y=\"138\" width=\"136\" height=\"48\" rx=\"24\"></rect><text class=\"dg-label\" text-anchor=\"middle\"><tspan x=\"80\" y=\"166.5\">Client</tspan></text><rect class=\"dg-node dg-box\" x=\"172\" y=\"136\" width=\"136\" height=\"52\" rx=\"8\"></rect><text class=\"dg-label\" text-anchor=\"middle\"><tspan x=\"240\" y=\"158.5\">Web server</tspan><tspan x=\"240\" y=\"174.5\">(reverse proxy)</tspan></text><rect class=\"dg-node dg-box\" x=\"332\" y=\"18\" width=\"136\" height=\"48\" rx=\"8\"></rect><text class=\"dg-label\" text-anchor=\"middle\"><tspan x=\"400\" y=\"46.5\">Read API</tspan></text><rect class=\"dg-node dg-box\" x=\"332\" y=\"258\" width=\"136\" height=\"48\" rx=\"8\"></rect><text class=\"dg-label\" text-anchor=\"middle\"><tspan x=\"400\" y=\"286.5\">Sales API</tspan></text><rect class=\"dg-node dg-box\" x=\"492\" y=\"136\" width=\"136\" height=\"52\" rx=\"8\"></rect><text class=\"dg-label\" text-anchor=\"middle\"><tspan x=\"560\" y=\"158.5\">Sales Rank</tspan><tspan x=\"560\" y=\"174.5\">Service</tspan></text><path class=\"dg-node dg-store\" d=\"M652,18 a68,7 0 0,1 136,0 v48 a68,7 0 0,1 -136,0 z\"></path><path class=\"dg-line\" d=\"M652,18 a68,7 0 0,0 136,0\"></path><text class=\"dg-label\" text-anchor=\"middle\"><tspan x=\"720\" y=\"41.5\">SQL database</tspan><tspan x=\"720\" y=\"57.5\">(sales_rank)</tspan></text><path class=\"dg-node dg-store\" d=\"M652,258 a68,7 0 0,1 136,0 v48 a68,7 0 0,1 -136,0 z\"></path><path class=\"dg-line\" d=\"M652,258 a68,7 0 0,0 136,0\"></path><text class=\"dg-label\" text-anchor=\"middle\"><tspan x=\"720\" y=\"281.5\">Object store</tspan><tspan x=\"720\" y=\"297.5\">(sales logs)</tspan></text><rect class=\"dg-edge-bg\" x=\"516.8\" y=\"33\" width=\"84.4\" height=\"18\" rx=\"4\"></rect><text class=\"dg-edge-label\" x=\"559\" y=\"46\" text-anchor=\"middle\">top products</text><rect class=\"dg-edge-bg\" x=\"523\" y=\"273\" width=\"72\" height=\"18\" rx=\"4\"></rect><text class=\"dg-edge-label\" x=\"559\" y=\"286\" text-anchor=\"middle\">append log</text><rect class=\"dg-edge-bg\" x=\"602\" y=\"211.5\" width=\"72\" height=\"18\" rx=\"4\"></rect><text class=\"dg-edge-label\" x=\"638\" y=\"224.5\" text-anchor=\"middle\">hourly job</text><rect class=\"dg-edge-bg\" x=\"593.1\" y=\"96.5\" width=\"84.4\" height=\"18\" rx=\"4\"></rect><text class=\"dg-edge-label\" x=\"635.3\" y=\"109.5\" text-anchor=\"middle\">load results</text></svg></div><figcaption>Sales rank: the first design</figcaption></figure>\n<ul>\n<li><strong>Client.</strong> A browser or app showing a category's best sellers, and the checkout flow that reports sales.</li>\n<li><strong>Web server.</strong> A <a href=\"/learn/reverse-proxy-and-api-gateway#what-a-reverse-proxy-is\">reverse proxy</a> that terminates HTTPS and forwards each request to the right API server.</li>\n<li><strong>Sales API.</strong> Receives each completed sale and appends it to a log.</li>\n<li><strong>Object store.</strong> A managed store for files, such as Amazon S3, that holds the sales logs. It's cheaper and simpler than running our own distributed file system, and it handles the 40 GB a month easily.</li>\n<li><strong>Sales Rank Service.</strong> A batch job that runs every hour. It reads the past week of logs, counts units per category and product, sorts them, and writes the result.</li>\n<li><strong>SQL database.</strong> Holds the <code>sales_rank</code> table, the precomputed answer. It's the only thing the read path needs.</li>\n<li><strong>Read API.</strong> Answers \"what are the top products in category X\" by reading <code>sales_rank</code>.</li>\n</ul>","headings":[{"id":"step-2-create-a-high-level-design","title":"Step 2: Create a high-level design","depth":3}]},{"id":"step-3-design-core-components","title":"Step 3: Design core components","html":"<h3 id=\"step-3-design-core-components\">Step 3: Design core components</h3>\n<h4 id=\"use-case-service-calculates-the-past-weeks-most-popular-products-by-category\">Use case: Service calculates the past week's most popular products by category</h4>\n<h5 id=\"the-sales-log\">The sales log</h5>\n<p>Every time a sale completes, the Sales API appends one line per category the product belongs to. A product in two categories produces two lines for one sale. Writing the category into the log at sale time keeps the ranking job simple: it never has to look up which categories a product is in. This is safe because we assumed products never change category. The edge cases section revisits this choice.</p>\n<p>The Sales API writes lines to a local file and ships each finished file to the object store every few minutes. Files are stored under a prefix for the hour they cover, for example <code>sales/2026/10/18/13/part-0007.gz</code>. That layout matters later: a job that needs one week of data reads exactly 168 hourly prefixes and never touches older files.</p>\n<p>Here is a sample of the log, tab-delimited:</p>\n<pre class=\"shiki shiki-themes github-light github-dark\" style=\"background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8\" tabindex=\"0\"><code><span class=\"line\"><span>timestamp             product_id  category_id  qty  total_price  seller_id  buyer_id</span></span>\n<span class=\"line\"><span>2026-10-12T09:14:03Z  1001        12           2    39.98        501        90017</span></span>\n<span class=\"line\"><span>2026-10-12T09:14:03Z  1001        40           2    39.98        501        90017</span></span>\n<span class=\"line\"><span>2026-10-14T11:29:47Z  2002        12           5    24.95        733        91020</span></span>\n<span class=\"line\"><span>2026-10-16T20:05:31Z  3003        40           4    59.96        812        90017</span></span>\n<span class=\"line\"><span>2026-10-18T13:12:09Z  4004        12           2    5.98         950        92611</span></span>\n<span class=\"line\"><span>2026-10-03T10:00:00Z  2002        12           9    44.91        733        93001</span></span></code></pre>\n<p>The first two lines are one sale of product 1001, which is in categories 12 and 40. The last line is older than a week, so a ranking computed at midnight on October 19 should ignore it.</p>\n<p><strong>Clarify with your interviewer how much code they expect.</strong> The core of the job fits in a few short functions, so it's worth sketching.</p>\n<h5 id=\"the-ranking-job-two-passes-of-mapreduce\">The ranking job: two passes of MapReduce</h5>\n<p><strong>MapReduce</strong> is a way to process a large data set on many machines by writing just two functions. A <strong>map</strong> function reads one input record and emits zero or more key-value pairs. The framework then <strong>shuffles</strong> the pairs: it sorts them and sends every pair with the same key to the same machine. A <strong>reduce</strong> function receives one key with all of its values and emits the result. The framework handles splitting the input, moving data between machines and retrying failed tasks. The <a href=\"/learn/batch-processing#mapreduce-the-foundational-model\">batch processing</a> chapter explains how it works underneath. Hadoop and Spark both run jobs of this shape.</p>\n<p>The job runs as two passes:</p>\n<ol>\n<li><strong>Pass 1, count.</strong> The map step reads each log line and, if the sale falls inside the window, emits the key <code>(category_id, product_id)</code> with the value <code>quantity</code>. The reduce step sums the quantities for each key. The output is the total units sold per product per category.</li>\n<li><strong>Pass 2, sort.</strong> The map step rewrites each total so the sort key is <code>(category_id, -total, product_id)</code>. The shuffle then does a distributed sort on that key. The reduce step reads each category's products in order, assigns ranks 1, 2, 3 and so on, and keeps the top N.</li>\n</ol>\n<p>Here is the logic in Python, with a small driver that plays the framework's part on one machine so the code can be tested:</p>\n<pre class=\"shiki shiki-themes github-light github-dark\" style=\"background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8\" tabindex=\"0\"><code><span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">from</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> datetime </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">import</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> datetime, timedelta, timezone</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">from</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> itertools </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">import</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> groupby</span></span>\n<span class=\"line\"></span>\n<span class=\"line\"><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">WINDOW</span><span style=\"color:#D73A49;--shiki-dark:#F97583\"> =</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> timedelta(</span><span style=\"color:#E36209;--shiki-dark:#FFAB70\">days</span><span style=\"color:#D73A49;--shiki-dark:#F97583\">=</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">7</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">)</span></span>\n<span class=\"line\"><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">TOP_N</span><span style=\"color:#D73A49;--shiki-dark:#F97583\"> =</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\"> 100</span></span>\n<span class=\"line\"></span>\n<span class=\"line\"></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">def</span><span style=\"color:#6F42C1;--shiki-dark:#B392F0\"> parse</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">(line):</span></span>\n<span class=\"line\"><span style=\"color:#032F62;--shiki-dark:#9ECBFF\">    \"\"\"Split one tab-delimited log line into the fields the job needs.\"\"\"</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">    ts, product_id, category_id, qty, _price, _seller, _buyer </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">=</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> line.split(</span><span style=\"color:#032F62;--shiki-dark:#9ECBFF\">\"</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">\\t</span><span style=\"color:#032F62;--shiki-dark:#9ECBFF\">\"</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">)</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">    return</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> (datetime.fromisoformat(ts), </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">int</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">(product_id),</span></span>\n<span class=\"line\"><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">            int</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">(category_id), </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">int</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">(qty))</span></span>\n<span class=\"line\"></span>\n<span class=\"line\"></span>\n<span class=\"line\"><span style=\"color:#6A737D;--shiki-dark:#6A737D\"># Pass 1: total units per (category, product) inside the window.</span></span>\n<span class=\"line\"></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">def</span><span style=\"color:#6F42C1;--shiki-dark:#B392F0\"> map_sales</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">(line, window_start, window_end):</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">    ts, product_id, category_id, qty </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">=</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> parse(line)</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">    if</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> window_start </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">&#x3C;=</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> ts </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">&#x3C;</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> window_end:</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">        yield</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> (category_id, product_id), qty</span></span>\n<span class=\"line\"></span>\n<span class=\"line\"></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">def</span><span style=\"color:#6F42C1;--shiki-dark:#B392F0\"> reduce_sum</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">(key, quantities):</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">    yield</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> key, </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">sum</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">(quantities)</span></span>\n<span class=\"line\"></span>\n<span class=\"line\"></span>\n<span class=\"line\"><span style=\"color:#6A737D;--shiki-dark:#6A737D\"># Pass 2: order each category by units sold, highest first.</span></span>\n<span class=\"line\"></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">def</span><span style=\"color:#6F42C1;--shiki-dark:#B392F0\"> map_sort_key</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">(key, total):</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">    category_id, product_id </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">=</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> key</span></span>\n<span class=\"line\"><span style=\"color:#6A737D;--shiki-dark:#6A737D\">    # Negate the total so an ascending sort puts best sellers first.</span></span>\n<span class=\"line\"><span style=\"color:#6A737D;--shiki-dark:#6A737D\">    # product_id breaks ties, so the order is the same on every run.</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">    yield</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> (category_id, </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">-</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">total, product_id), </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">None</span></span>\n<span class=\"line\"></span>\n<span class=\"line\"></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">def</span><span style=\"color:#6F42C1;--shiki-dark:#B392F0\"> reduce_rank</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">(category_id, sorted_keys):</span></span>\n<span class=\"line\"><span style=\"color:#032F62;--shiki-dark:#9ECBFF\">    \"\"\"Receives one category's keys, already sorted by the shuffle.\"\"\"</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">    for</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> rank, (_cat, neg_total, product_id) </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">in</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\"> enumerate</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">(sorted_keys, </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">1</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">):</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">        if</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> rank </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">></span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\"> TOP_N</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">:</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">            break</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">        yield</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> category_id, rank, product_id, </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">-</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">neg_total</span></span>\n<span class=\"line\"></span>\n<span class=\"line\"></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">def</span><span style=\"color:#6F42C1;--shiki-dark:#B392F0\"> run_locally</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">(lines, window_end):</span></span>\n<span class=\"line\"><span style=\"color:#032F62;--shiki-dark:#9ECBFF\">    \"\"\"A one-machine stand-in for the framework, to test the logic.\"\"\"</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">    window_start </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">=</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> window_end </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">-</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\"> WINDOW</span></span>\n<span class=\"line\"></span>\n<span class=\"line\"><span style=\"color:#6A737D;--shiki-dark:#6A737D\">    # Pass 1: map, then shuffle (group by key), then reduce.</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">    pairs </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">=</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> [kv </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">for</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> line </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">in</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> lines</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">             for</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> kv </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">in</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> map_sales(line, window_start, window_end)]</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">    pairs.sort(</span><span style=\"color:#E36209;--shiki-dark:#FFAB70\">key</span><span style=\"color:#D73A49;--shiki-dark:#F97583\">=lambda</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> kv: kv[</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">0</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">])</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">    totals </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">=</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> [out </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">for</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> key, group </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">in</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> groupby(pairs, </span><span style=\"color:#E36209;--shiki-dark:#FFAB70\">key</span><span style=\"color:#D73A49;--shiki-dark:#F97583\">=lambda</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> kv: kv[</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">0</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">])</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">              for</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> out </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">in</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> reduce_sum(key, (qty </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">for</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> _, qty </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">in</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> group))]</span></span>\n<span class=\"line\"></span>\n<span class=\"line\"><span style=\"color:#6A737D;--shiki-dark:#6A737D\">    # Pass 2: sort on the composite key, partition by category.</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">    keys </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">=</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\"> sorted</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">(k </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">for</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> key, total </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">in</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> totals</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">                  for</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> k, _ </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">in</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> map_sort_key(key, total))</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">    for</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> category_id, group </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">in</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> groupby(keys, </span><span style=\"color:#E36209;--shiki-dark:#FFAB70\">key</span><span style=\"color:#D73A49;--shiki-dark:#F97583\">=lambda</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> k: k[</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">0</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">]):</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">        yield from</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> reduce_rank(category_id, group)</span></span></code></pre>\n<p>Running it on the sample log with <code>window_end</code> set to midnight UTC on October 19, 2026 gives:</p>\n<pre class=\"shiki shiki-themes github-light github-dark\" style=\"background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8\" tabindex=\"0\"><code><span class=\"line\"><span>pass 1 output                  pass 2 output (category, rank, product, units)</span></span>\n<span class=\"line\"><span>(12, 1001) -> 2                (12, 1, 2002, 5)</span></span>\n<span class=\"line\"><span>(12, 2002) -> 5                (12, 2, 1001, 2)</span></span>\n<span class=\"line\"><span>(12, 4004) -> 2                (12, 3, 4004, 2)</span></span>\n<span class=\"line\"><span>(40, 1001) -> 2                (40, 1, 3003, 4)</span></span>\n<span class=\"line\"><span>(40, 3003) -> 4                (40, 2, 1001, 2)</span></span></code></pre>\n<p>The sale of 9 units of product 2002 on October 3 was dropped by the window check, so 2002 has 5 units in category 12, not 14. Products 1001 and 4004 tie at 2 units in category 12, and the lower product ID wins. We'll come back to whether that's fair.</p>\n<p>Three details make pass 2 work on a real cluster:</p>\n<ul>\n<li><strong>Sort descending.</strong> A shuffle sorts keys in ascending order. Putting <code>-total</code> in the key makes the best seller come first, so the reducer can stop after N products. Sorting on <code>total</code> directly would put the slowest sellers first.</li>\n<li><strong>Partition by category only.</strong> The framework decides which reducer gets a key by hashing a <strong>partition key</strong>. If it hashed the whole <code>(category, -total, product)</code> tuple, one category's products would be scattered over many reducers, and none could assign ranks. So we partition on <code>category_id</code> alone and let the sort order the rest of the key within each partition. This combination is called a <strong>secondary sort</strong>.</li>\n<li><strong>Prune early.</strong> After pass 1, each (category, product) pair appears exactly once with its final total. So each map task in pass 2 can safely keep only its own top N per category before the shuffle; no product it drops could make the overall top N. With 1,000 categories and N = 100, the shuffle moves at most 100,000 entries per map task instead of millions. This pruning would be wrong in pass 1, where a product's units are still spread over many map tasks.</li>\n</ul>\n<p>Each run reads only the 168 hourly prefixes in the window. The window check in <code>map_sales</code> is still needed, because the first and last files can contain a few lines just outside the boundary. Without the hourly layout, the job would have to read every log ever written just to throw most of it away: about 1.5 TB after three years, to use 10 GB.</p>\n<h5 id=\"the-sales_rank-table\">The <code>sales_rank</code> table</h5>\n<p>The job's output goes into a table in a SQL database:</p>\n<pre class=\"shiki shiki-themes github-light github-dark\" style=\"background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8\" tabindex=\"0\"><code><span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">CREATE</span><span style=\"color:#D73A49;--shiki-dark:#F97583\"> TABLE</span><span style=\"color:#6F42C1;--shiki-dark:#B392F0\"> sales_rank</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> (</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">    id           </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">BIGINT</span><span style=\"color:#D73A49;--shiki-dark:#F97583\">    NOT NULL</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> AUTO_INCREMENT,</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">    run_id       </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">BIGINT</span><span style=\"color:#D73A49;--shiki-dark:#F97583\">    NOT NULL</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">,   </span><span style=\"color:#6A737D;--shiki-dark:#6A737D\">-- which hourly run produced this row</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">    category_id  </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">INT</span><span style=\"color:#D73A49;--shiki-dark:#F97583\">       NOT NULL</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">,</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">    rank_in_category </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">INT</span><span style=\"color:#D73A49;--shiki-dark:#F97583\">   NOT NULL</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">,</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">    product_id   </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">BIGINT</span><span style=\"color:#D73A49;--shiki-dark:#F97583\">    NOT NULL</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">,</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">    total_sold   </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">INT</span><span style=\"color:#D73A49;--shiki-dark:#F97583\">       NOT NULL</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">,</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">    PRIMARY KEY</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> (id),</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">    FOREIGN KEY</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> (category_id) </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">REFERENCES</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> categories(id),</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">    FOREIGN KEY</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> (product_id)  </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">REFERENCES</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> products(id),</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">    UNIQUE</span><span style=\"color:#D73A49;--shiki-dark:#F97583\"> KEY</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> by_category (run_id, category_id, rank_in_category),</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">    KEY</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> by_product (run_id, product_id)</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">);</span></span>\n<span class=\"line\"></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">CREATE</span><span style=\"color:#D73A49;--shiki-dark:#F97583\"> TABLE</span><span style=\"color:#6F42C1;--shiki-dark:#B392F0\"> sales_rank_current</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> (</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">    id      </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">INT</span><span style=\"color:#D73A49;--shiki-dark:#F97583\">    NOT NULL</span><span style=\"color:#D73A49;--shiki-dark:#F97583\"> PRIMARY KEY</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">,   </span><span style=\"color:#6A737D;--shiki-dark:#6A737D\">-- always 1</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">    run_id  </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">BIGINT</span><span style=\"color:#D73A49;--shiki-dark:#F97583\"> NOT NULL</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">,</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">    window_start </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">TIMESTAMP</span><span style=\"color:#D73A49;--shiki-dark:#F97583\"> NOT NULL</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">,</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">    window_end   </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">TIMESTAMP</span><span style=\"color:#D73A49;--shiki-dark:#F97583\"> NOT NULL</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">);</span></span></code></pre>\n<ul>\n<li><code>id</code> is a surrogate primary key. It's indexed automatically.</li>\n<li><code>category_id</code> and <code>product_id</code> refer to the catalog's tables. If those live in another team's database, the foreign keys become a documented convention instead of a constraint.</li>\n<li>The <code>by_category</code> index serves the main query, \"top N products in category X\". Because it includes <code>rank_in_category</code>, the database reads N consecutive index entries and stops.</li>\n<li>The <code>by_product</code> index serves \"what are this product's ranks?\", which a product page needs.</li>\n<li><code>run_id</code> lets each hourly run write a complete new set of rows next to the old one. The tiny <code>sales_rank_current</code> table says which run is live. Publishing a run is one update to that table, so readers switch from the old ranking to the new one all at once and never see a half-loaded result. A cleanup job deletes runs older than a day or two.</li>\n</ul>\n<p>Indexes make lookups take time proportional to the logarithm of the table size instead of scanning every row, and they help keep the hot data in memory. That matters: reading 1 MB sequentially from memory takes about 250 microseconds, from an SSD about 1 ms (4 times longer), and from a spinning disk about 20 ms (80 times longer), according to the widely shared table of latency numbers credited to Jeff Dean. At 2 GB for the full table, or 10 MB for the top 100 per category, this table fits in memory on any database server. See <a href=\"/learn/relational-databases#use-good-indexes\">Use good indexes</a> for how indexes work.</p>\n<p>Why a relational database here? The data is small, the queries are simple lookups, and the hourly bulk load is easy to do in a transaction-friendly way. A key-value store would work too, for example storing each category's top list as one value. The trade-offs section compares the two.</p>\n<h4 id=\"use-case-user-views-the-past-weeks-most-popular-products-by-category\">Use case: User views the past week's most popular products by category</h4>\n<p>The read path:</p>\n<ol>\n<li>The <strong>client</strong> sends a request to the <strong>web server</strong>, which runs as a reverse proxy.</li>\n<li>The <strong>web server</strong> forwards it to a <strong>Read API</strong> server.</li>\n<li>The <strong>Read API</strong> looks up the live <code>run_id</code> and reads the category's rows from <code>sales_rank</code>.</li>\n</ol>\n<p>The query behind it:</p>\n<pre class=\"shiki shiki-themes github-light github-dark\" style=\"background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8\" tabindex=\"0\"><code><span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">SELECT</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\"> r</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">.</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">rank_in_category</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">, </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">r</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">.</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">product_id</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">, </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">r</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">.</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">total_sold</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">FROM</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> sales_rank r</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">JOIN</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> sales_rank_current c </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">ON</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\"> c</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">.</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">id</span><span style=\"color:#D73A49;--shiki-dark:#F97583\"> =</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\"> 1</span><span style=\"color:#D73A49;--shiki-dark:#F97583\"> AND</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\"> r</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">.</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">run_id</span><span style=\"color:#D73A49;--shiki-dark:#F97583\"> =</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\"> c</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">.</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">run_id</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">WHERE</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\"> r</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">.</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">category_id</span><span style=\"color:#D73A49;--shiki-dark:#F97583\"> =</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\"> 1234</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">  AND</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\"> r</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">.</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">rank_in_category</span><span style=\"color:#D73A49;--shiki-dark:#F97583\"> BETWEEN</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\"> 1</span><span style=\"color:#D73A49;--shiki-dark:#F97583\"> AND</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\"> 20</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">ORDER BY</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\"> r</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">.</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">rank_in_category</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">;</span></span></code></pre>\n<p>The public interface is a <a href=\"/learn/protocols-and-apis#rest-resources-and-representations\">REST</a> endpoint:</p>\n<pre class=\"shiki shiki-themes github-light github-dark\" style=\"background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8\" tabindex=\"0\"><code><span class=\"line\"><span>GET https://shop.example.com/api/v1/popular?category_id=1234&#x26;limit=20</span></span></code></pre>\n<pre class=\"shiki shiki-themes github-light github-dark\" style=\"background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8\" tabindex=\"0\"><code><span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">{</span></span>\n<span class=\"line\"><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">  \"category_id\"</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">: </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">1234</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">,</span></span>\n<span class=\"line\"><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">  \"window_start\"</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">: </span><span style=\"color:#032F62;--shiki-dark:#9ECBFF\">\"2026-10-12T13:00:00Z\"</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">,</span></span>\n<span class=\"line\"><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">  \"window_end\"</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">: </span><span style=\"color:#032F62;--shiki-dark:#9ECBFF\">\"2026-10-19T13:00:00Z\"</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">,</span></span>\n<span class=\"line\"><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">  \"products\"</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">: [</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">    {</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">\"rank\"</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">: </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">1</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">, </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">\"product_id\"</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">: </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">50</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">, </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">\"total_sold\"</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">: </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">100000</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">},</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">    {</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">\"rank\"</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">: </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">2</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">, </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">\"product_id\"</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">: </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">200</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">, </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">\"total_sold\"</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">: </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">90000</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">},</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">    {</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">\"rank\"</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">: </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">3</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">, </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">\"product_id\"</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">: </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">3</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">, </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">\"total_sold\"</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">: </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">80000</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">}</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">  ],</span></span>\n<span class=\"line\"><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">  \"next_cursor\"</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">: </span><span style=\"color:#032F62;--shiki-dark:#9ECBFF\">\"rank:4\"</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">}</span></span></code></pre>\n<ul>\n<li>The response says which window it covers, so a client can tell how fresh it is.</li>\n<li><code>limit</code> and <code>next_cursor</code> page through longer lists. Since rank is a stable integer within a run, the cursor can simply be the next rank. The <a href=\"/learn/protocols-and-apis#pagination\">pagination</a> section covers the alternatives.</li>\n<li>Whether to show <code>total_sold</code> publicly is a business decision. Exact sales numbers tell competitors a lot. The internal API can return them while the public one returns ranks only.</li>\n<li>The page also needs product names, prices and images. Those come from the catalog service by ID and are cached separately.</li>\n</ul>\n<p>Inside the data center, services such as the Read API and the catalog service can talk to each other over <a href=\"/learn/protocols-and-apis#rpc-calling-a-function-on-another-machine\">RPC</a> such as gRPC. REST suits the public API because any client can call it and HTTP caches understand it.</p>\n<h5 id=\"going-further-a-sliding-window-done-incrementally\">Going further: a sliding window, done incrementally</h5>\n<p>\"The past week\" moves forward every hour. A <strong>sliding window</strong> is a window of fixed length (here 168 hours) that advances by a smaller step (here 1 hour), so consecutive windows overlap and each sale belongs to 168 of them. Stream processors use the same term: Apache Flink's documentation describes windows with a size and a separate \"slide\", and notes that elements are assigned to several windows when the slide is smaller than the size.</p>\n<p>Recomputing all 168 hours every hour reads about 10 GB to account for 58 MB of new data. That's affordable at this size, and it has a real advantage: every run starts from the raw log, so a bug fix or a late file is picked up automatically on the next run. But it grows with the window. A 30-day window would mean reading about 42 GB every hour.</p>\n<p>The incremental version keeps hourly partial counts:</p>\n<ol>\n<li>Every hour, run pass 1 on just the hour that ended, and store its totals per (category, product) as a small file, for example <code>hourly_counts/2026/10/18/13/</code>.</li>\n<li>Keep a running total for the current window. To slide it forward by one hour, add the newest hour's counts and subtract the counts of the hour that just left the window.</li>\n<li>Run pass 2 on the running totals to produce the new ranking.</li>\n</ol>\n<pre class=\"shiki shiki-themes github-light github-dark\" style=\"background-color:#fff;--shiki-dark-bg:#24292e;color:#24292e;--shiki-dark:#e1e4e8\" tabindex=\"0\"><code><span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">def</span><span style=\"color:#6F42C1;--shiki-dark:#B392F0\"> slide_window</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">(running, newest_hour, expired_hour):</span></span>\n<span class=\"line\"><span style=\"color:#032F62;--shiki-dark:#9ECBFF\">    \"\"\"Each argument maps (category_id, product_id) -> units.\"\"\"</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">    for</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> key, units </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">in</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> newest_hour.items():</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">        running[key] </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">=</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> running.get(key, </span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\">0</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">) </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">+</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> units</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">    for</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> key, units </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">in</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> expired_hour.items():</span></span>\n<span class=\"line\"><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">        running[key] </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">-=</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> units</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">        if</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> running[key] </span><span style=\"color:#D73A49;--shiki-dark:#F97583\">==</span><span style=\"color:#005CC5;--shiki-dark:#79B8FF\"> 0</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\">:</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">            del</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> running[key]</span></span>\n<span class=\"line\"><span style=\"color:#D73A49;--shiki-dark:#F97583\">    return</span><span style=\"color:#24292E;--shiki-dark:#E1E4E8\"> running</span></span></code></pre>\n<p>The cost is that errors stick. If a log file arrives late, or a bad hour is counted twice, the running total stays wrong until someone fixes it. One compromise is to slide incrementally every hour and rebuild the running total from the 168 hourly files once a day, which bounds how long any error can last.</p>\n<h5 id=\"going-further-edge-cases\">Going further: edge cases</h5>\n<p><strong>Returns and cancellations.</strong> A product that sells 1,000 units and gets 900 back isn't popular. To count returns, log them as events with a negative quantity, then decide which hour they belong to. The hour of the original sale is most accurate, but it means rewriting an hour that may already be summed. The hour of the return is simpler; the sale and the return may then fall in different windows, so clamp each total at zero. For a best-seller list, the simpler rule is usually good enough.</p>\n<p><strong>A product in several categories.</strong> We fan out at write time: one log line per category. That keeps the job simple and works because categories never change. If they could change, write-time fan-out would keep counting a sale under a category the product has left. The alternative is to log only <code>product_id</code> and join to a product-to-categories table inside the map step. That table has 10 million products × 2 categories × about 12 bytes ≈ 240 MB, small enough to load into memory on every map task. Remember, too, that per-category ranks don't add up to an overall rank: a product's total in \"Kitchen Scales\" and in \"Baking Tools\" is the same set of sales counted twice.</p>\n<p><strong>Ties.</strong> Two products with the same units must still get an order, and the order should be the same on every run. Otherwise a cache filled from one replica and a page served from another can show two products swapping places for no reason. Our sort key uses <code>product_id</code> as the tiebreaker, which is stable but arbitrary. Fairer rules include ranking by revenue, or by which product reached the total first. The <a href=\"/learn/design-gaming-leaderboard#breaking-ties\">leaderboard design</a> shows how to pack a tiebreaker into a single sort key. You also need to decide how ties display: \"1, 2, 2, 4\" (shared rank) or \"1, 2, 3, 4\" (every position unique). Pick one and use it everywhere.</p>\n<p><strong>What counts as a sale.</strong> Counting units lets one bulk order of 500 pens beat 300 separate buyers. Counting orders, or distinct buyers, resists that and also makes it harder for a seller to buy their own product to climb the list. Since <code>buyer_id</code> is in the log, any of these is a small change to the map step.</p>","headings":[{"id":"step-3-design-core-components","title":"Step 3: Design core components","depth":3},{"id":"use-case-service-calculates-the-past-weeks-most-popular-products-by-category","title":"Use case: Service calculates the past week's most popular products by category","depth":4},{"id":"use-case-user-views-the-past-weeks-most-popular-products-by-category","title":"Use case: User views the past week's most popular products by category","depth":4}]},{"id":"step-4-scale-the-design","title":"Step 4: Scale the design","html":"<h3 id=\"step-4-scale-the-design\">Step 4: Scale the design</h3>\n<figure class=\"diagram\" data-text=\"Client -> DNS; Client -> CDN; Client -> Load balancer; Load balancer -> Web servers; Web servers -> Read API; Web servers -> Sales API; Read API -> Memory cache; Read API -> SQL read replicas; SQL primary (+ standby) -> SQL read replicas (replication); Sales API -> Object store (sales logs); Object store -> Sales Rank Service; Sales Rank Service -> SQL primary (+ standby) (load run); Object store -> Analytics database (load)\"><div class=\"diagram-scroll\"><svg class=\"dg\" viewBox=\"0 0 800 445\" width=\"800\" role=\"img\" aria-label=\"Sales rank, scaled out (internal load balancers not shown)\"><defs><marker id=\"dg-arrow\" viewBox=\"0 0 10 10\" refX=\"9\" refY=\"5\" markerWidth=\"7\" markerHeight=\"7\" orient=\"auto-start-reverse\"><path class=\"dg-arrowhead\" d=\"M0,1 L9,5 L0,9 z\"></path></marker></defs><line class=\"dg-edge\" x1=\"80\" y1=\"135\" x2=\"80\" y2=\"71\" marker-end=\"url(#dg-arrow)\"></line><line class=\"dg-edge\" x1=\"80\" y1=\"189\" x2=\"80\" y2=\"253\" marker-end=\"url(#dg-arrow)\"></line><line class=\"dg-edge\" x1=\"151\" y1=\"162\" x2=\"167\" y2=\"162\" marker-end=\"url(#dg-arrow)\"></line><line class=\"dg-edge\" x1=\"311\" y1=\"162\" x2=\"327\" y2=\"162\" marker-end=\"url(#dg-arrow)\"></line><line class=\"dg-edge\" x1=\"471\" y1=\"162\" x2=\"487\" y2=\"162\" marker-end=\"url(#dg-arrow)\"></line><line class=\"dg-edge\" x1=\"436\" y1=\"189\" x2=\"521.3\" y2=\"253\" marker-end=\"url(#dg-arrow)\"></line><line class=\"dg-edge\" x1=\"596\" y1=\"135\" x2=\"674.7\" y2=\"76\" marker-end=\"url(#dg-arrow)\"></line><line class=\"dg-edge\" x1=\"631\" y1=\"162\" x2=\"647\" y2=\"162\" marker-end=\"url(#dg-arrow)\"></line><line class=\"dg-edge\" x1=\"720\" y1=\"248\" x2=\"720\" y2=\"198\" marker-end=\"url(#dg-arrow)\"></line><line class=\"dg-edge\" x1=\"560\" y1=\"309\" x2=\"560\" y2=\"368\" marker-end=\"url(#dg-arrow)\"></line><line class=\"dg-edge\" x1=\"631\" y1=\"402\" x2=\"647\" y2=\"402\" marker-end=\"url(#dg-arrow)\"></line><line class=\"dg-edge\" x1=\"720\" y1=\"373\" x2=\"720\" y2=\"318\" marker-end=\"url(#dg-arrow)\"></line><line class=\"dg-edge\" x1=\"489\" y1=\"402\" x2=\"473\" y2=\"402\" marker-end=\"url(#dg-arrow)\"></line><rect class=\"dg-node dg-box\" x=\"12\" y=\"18\" width=\"136\" height=\"48\" rx=\"8\"></rect><text class=\"dg-label\" text-anchor=\"middle\"><tspan x=\"80\" y=\"46.5\">DNS</tspan></text><rect class=\"dg-node dg-client\" x=\"12\" y=\"138\" width=\"136\" height=\"48\" rx=\"24\"></rect><text class=\"dg-label\" text-anchor=\"middle\"><tspan x=\"80\" y=\"166.5\">Client</tspan></text><rect class=\"dg-node dg-box\" x=\"12\" y=\"258\" width=\"136\" height=\"48\" rx=\"8\"></rect><text class=\"dg-label\" text-anchor=\"middle\"><tspan x=\"80\" y=\"286.5\">CDN</tspan></text><rect class=\"dg-node dg-box\" x=\"172\" y=\"138\" width=\"136\" height=\"48\" rx=\"8\"></rect><text class=\"dg-label\" text-anchor=\"middle\"><tspan x=\"240\" y=\"166.5\">Load balancer</tspan></text><rect class=\"dg-node dg-box\" x=\"332\" y=\"138\" width=\"136\" height=\"48\" rx=\"8\"></rect><text class=\"dg-label\" text-anchor=\"middle\"><tspan x=\"400\" y=\"166.5\">Web servers</tspan></text><rect class=\"dg-node dg-box\" x=\"492\" y=\"138\" width=\"136\" height=\"48\" rx=\"8\"></rect><text class=\"dg-label\" text-anchor=\"middle\"><tspan x=\"560\" y=\"166.5\">Read API</tspan></text><rect class=\"dg-node dg-box\" x=\"492\" y=\"258\" width=\"136\" height=\"48\" rx=\"8\"></rect><text class=\"dg-label\" text-anchor=\"middle\"><tspan x=\"560\" y=\"286.5\">Sales API</tspan></text><path class=\"dg-node dg-store\" d=\"M652,20 a68,7 0 0,1 136,0 v44 a68,7 0 0,1 -136,0 z\"></path><path class=\"dg-line\" d=\"M652,20 a68,7 0 0,0 136,0\"></path><text class=\"dg-label\" text-anchor=\"middle\"><tspan x=\"720\" y=\"49.5\">Memory cache</tspan></text><path class=\"dg-node dg-store\" d=\"M652,138 a68,7 0 0,1 136,0 v48 a68,7 0 0,1 -136,0 z\"></path><path class=\"dg-line\" d=\"M652,138 a68,7 0 0,0 136,0\"></path><text class=\"dg-label\" text-anchor=\"middle\"><tspan x=\"720\" y=\"161.5\">SQL read</tspan><tspan x=\"720\" y=\"177.5\">replicas</tspan></text><path class=\"dg-node dg-store\" d=\"M652,258 a68,7 0 0,1 136,0 v48 a68,7 0 0,1 -136,0 z\"></path><path class=\"dg-line\" d=\"M652,258 a68,7 0 0,0 136,0\"></path><text class=\"dg-label\" text-anchor=\"middle\"><tspan x=\"720\" y=\"281.5\">SQL primary</tspan><tspan x=\"720\" y=\"297.5\">(+ standby)</tspan></text><path class=\"dg-node dg-store\" d=\"M492,380 a68,7 0 0,1 136,0 v44 a68,7 0 0,1 -136,0 z\"></path><path class=\"dg-line\" d=\"M492,380 a68,7 0 0,0 136,0\"></path><text class=\"dg-label\" text-anchor=\"middle\"><tspan x=\"560\" y=\"409.5\">Object store</tspan></text><rect class=\"dg-node dg-box\" x=\"652\" y=\"376\" width=\"136\" height=\"52\" rx=\"8\"></rect><text class=\"dg-label\" text-anchor=\"middle\"><tspan x=\"720\" y=\"398.5\">Sales Rank</tspan><tspan x=\"720\" y=\"414.5\">Service</tspan></text><path class=\"dg-node dg-store\" d=\"M332,378 a68,7 0 0,1 136,0 v48 a68,7 0 0,1 -136,0 z\"></path><path class=\"dg-line\" d=\"M332,378 a68,7 0 0,0 136,0\"></path><text class=\"dg-label\" text-anchor=\"middle\"><tspan x=\"400\" y=\"401.5\">Analytics</tspan><tspan x=\"400\" y=\"417.5\">database</tspan></text><rect class=\"dg-edge-bg\" x=\"680.9\" y=\"214\" width=\"78.2\" height=\"18\" rx=\"4\"></rect><text class=\"dg-edge-label\" x=\"720\" y=\"227\" text-anchor=\"middle\">replication</text><rect class=\"dg-edge-bg\" x=\"524\" y=\"329.5\" width=\"72\" height=\"18\" rx=\"4\"></rect><text class=\"dg-edge-label\" x=\"560\" y=\"342.5\" text-anchor=\"middle\">sales logs</text><rect class=\"dg-edge-bg\" x=\"690.2\" y=\"336.5\" width=\"59.6\" height=\"18\" rx=\"4\"></rect><text class=\"dg-edge-label\" x=\"720\" y=\"349.5\" text-anchor=\"middle\">load run</text><rect class=\"dg-edge-bg\" x=\"463.6\" y=\"349\" width=\"34.8\" height=\"18\" rx=\"4\"></rect><text class=\"dg-edge-label\" x=\"481\" y=\"362\" text-anchor=\"middle\">load</text></svg></div><figcaption>Sales rank, scaled out (internal load balancers not shown)</figcaption></figure>\n<p>Don't jump straight from the first design to this one. In an interview, and in practice, the process is a loop:</p>\n<ol>\n<li><strong>Benchmark and load test</strong> the current design at the expected traffic.</li>\n<li><strong>Profile</strong> it to find the bottleneck.</li>\n<li><strong>Fix that bottleneck</strong>, weighing the alternatives and their costs.</li>\n<li><strong>Repeat.</strong></li>\n</ol>\n<p>The <a href=\"/learn/design-scaling-aws\">scaling AWS design</a> walks through that loop step by step for a general web app, and <a href=\"/learn/scalability\">Scalability</a> introduces each of the usual fixes. Here we take the numbers from step 1 and ask what breaks first.</p>\n<h4 id=\"the-read-path-40000-requests-a-second\">The read path: 40,000 requests a second</h4>\n<p>The first design sends every read to one SQL database, which can't keep up with 40,000 requests a second on average and about 120,000 at peak. But every request asks for one of 1,000 lists that change once an hour, so nearly every query repeats one the database answered a moment ago.</p>\n<p><strong>Memory cache.</strong> Put a <strong>memory cache</strong> such as Redis or Memcached between the Read API and the database, with keys like <code>popular:1234:page1</code>. The Read API checks the cache first and reads the database only on a miss. This pattern is called <a href=\"/learn/cache#cache-aside\">cache-aside</a>. The cache's working set is tiny: 1,000 categories × a few pages × 2 KB is under 10 MB, so every list stays in memory and the hit rate is close to 100%. The cache also absorbs the uneven traffic: a category that suddenly gets a burst of visits costs the database nothing extra.</p>\n<p>The risk is the top of every hour. If every key expires at the moment a new run is published, thousands of requests miss at once and all go to the database. This is a <strong>cache stampede</strong>, explained in <a href=\"/learn/cache#cache-stampede-thundering-herd\">Cache stampede (thundering herd)</a>. The cleanest fix here is for the Sales Rank Service to write the new lists into the cache itself when it publishes a run. That's a form of <a href=\"/learn/cache#refresh-ahead\">refresh-ahead</a>: readers never see a miss caused by the hourly change. Keep a TTL (time to live, an expiry time on each key) of a little over an hour as a safety net, with a few minutes of random jitter so keys don't all expire together.</p>\n<p><strong>CDN.</strong> Because the public response is the same for every user and changes at most once an hour, a <strong>CDN</strong> (content delivery network, a network of caches close to users) can serve it too. The API sets <code>Cache-Control: public, max-age=300</code>, and the CDN answers most requests without reaching our servers at all. That also takes care of most of the 80 to 240 MB a second of response bandwidth. The cost is staleness: a user may see the previous hour's list for up to five minutes after a new run. See <a href=\"/learn/cache#cdn-caching\">CDN caching</a> and <a href=\"/learn/dns-and-cdn#cache-control-directives\">Cache-Control directives</a>.</p>\n<p><strong>DNS.</strong> <a href=\"/learn/dns-and-cdn#how-dns-works\">DNS</a> points the API's name at the CDN and the load balancer, and with several regions can route each user to the nearest one.</p>\n<p><strong>Load balancer and more web and API servers.</strong> Requests that miss the CDN still need servers. A <a href=\"/learn/load-balancing#what-a-load-balancer-does\">load balancer</a> spreads them across several web servers and Read API servers, which run as identical, stateless copies. This is <strong>horizontal scaling</strong>: add copies to add capacity, and survive the loss of any one of them. The cost is one more component to run, which itself needs a standby. See <a href=\"/learn/load-balancing#horizontal-scaling-and-what-it-costs\">Horizontal scaling and what it costs</a>.</p>\n<p><strong>Separate web and API layers.</strong> Splitting the <strong>web servers</strong> (connections, TLS, routing) from the <strong>Read API</strong> and <strong>Sales API</strong> (application logic) lets each scale on its own: the read side needs many copies, the write side few. See <a href=\"/learn/reverse-proxy-and-api-gateway#separating-the-web-and-application-layers\">Separating the web and application layers</a>.</p>\n<p><strong>SQL read replicas.</strong> With the cache in place, the database sees few reads: misses after a cache node restarts, and the long tail of product-page lookups (\"what's this product's rank?\"), which spread across up to 20 million rows. <strong>Read replicas</strong> are copies of the database that receive every change from the primary and serve reads. Two or three replicas give room for those misses and keep the read path up if one fails. Replicas lag slightly behind the primary, but since publishing a run is one row change in <code>sales_rank_current</code>, a replica either shows the new run or the old one, never a mix. See <a href=\"/learn/relational-databases#primary-replica-replication\">Primary-replica replication</a>.</p>\n<h4 id=\"the-write-path-the-ranking-database-and-the-raw-sales-data\">The write path: the ranking database and the raw sales data</h4>\n<p><strong>What the SQL primary does.</strong> In this design the database that serves reads takes very few writes: one bulk load per hour of up to a few million rows, plus a one-row update to publish. The 400 transactions a second never touch it, because the Sales API appends them to the log. That's the main reason the design scales so well.</p>\n<p>If the business also wanted raw transactions in a SQL database, 400 inserts a second on average and about 1,200 at peak would land on one primary, and every insert would also have to reach each replica. That leaves little room for growth and would push us toward the scaling patterns below.</p>\n<p><strong>Fail-over for the primary.</strong> The primary is a single point of failure for publishing runs. Run it with a standby that takes over if it fails: a <strong>primary-standby</strong> pair, also called master-slave fail-over. While the primary is down, reads continue from the replicas and the cache with the last published run, which is exactly what the availability requirement asks for. See <a href=\"/learn/availability#fail-over-active-passive\">Fail-over: active-passive</a>.</p>\n<p><strong>Object store for history.</strong> The Sales API keeps writing logs to the object store, which handles 40 GB a month without any planning on our part. The ranking job only needs the last week. Older data can move to a cheaper storage class after a few weeks, and the serving database never holds raw history at all.</p>\n<p><strong>Analytics database.</strong> Analysts will want to ask questions the ranking job doesn't answer: sales by region, by seller, by hour of the day. Running those against the serving database would compete with the read path. Instead, load the logs into an <strong>analytics database</strong>, also called a <strong>data warehouse</strong>: a database built for scanning and aggregating large tables, usually by storing each column separately. Amazon Redshift, which AWS describes as \"a fully managed, petabyte-scale data warehouse service\", and Google BigQuery are examples. See <a href=\"/learn/batch-processing#data-warehouses-snowflake-google-bigquery-amazon-redshift\">Data warehouses</a>.</p>\n<p>The warehouse can also run the ranking itself. Pass 1 and pass 2 together are a <code>GROUP BY category_id, product_id</code> followed by a window function such as <code>ROW_NUMBER() OVER (PARTITION BY category_id ORDER BY total DESC, product_id)</code>. At 10 GB per run, a warehouse handles that easily, and a SQL query is easier for the next engineer to maintain than a MapReduce job. Keep MapReduce or Spark for when the logic outgrows SQL. Keep only a limited period in the warehouse, say the last few months, and leave the rest in the object store, where a query engine can still read it.</p>\n<h4 id=\"consistency-and-availability\">Consistency and availability</h4>\n<ul>\n<li><strong>What readers see.</strong> Readers can see a ranking up to about an hour old, plus the CDN's few minutes. That's <strong>eventual consistency</strong>: the system converges on the new answer without promising when. For a best-seller list, that's fine, and it's what lets every layer cache. See <a href=\"/learn/cap-and-consistency#the-consistency-spectrum\">The consistency spectrum</a>.</li>\n<li><strong>When the job fails.</strong> Because publishing is a single switch of <code>run_id</code>, a failed or half-finished run is never published. The previous run stays live and the cache keeps serving it. Alert if the live run gets older than two hours or so; users won't notice an hour's delay, but an engineer should.</li>\n<li><strong>Late or missing logs.</strong> If a Sales API host ships its files late, the run that should have counted them doesn't. A full recompute picks them up next hour; an incremental one needs the daily rebuild.</li>\n<li><strong>Redundancy.</strong> Run several copies of every stateless server, keep a standby for the primary, spread replicas and cache nodes across availability zones, and rely on the object store's own replication. See <a href=\"/learn/availability#redundancy-across-failure-domains\">Redundancy across failure domains</a>.</li>\n</ul>\n<h4 id=\"sql-scaling-patterns-if-the-database-grows\">SQL scaling patterns, if the database grows</h4>\n<p>The ranking table is small, so these aren't needed at the stated numbers. They matter if the scope grows, for example to millions of fine-grained categories, per-region rankings, or raw transactions stored in SQL.</p>\n<ul>\n<li><strong>Federation:</strong> split databases by function, so the sales rank tables live apart from catalog and order tables and don't compete with them. See <a href=\"/learn/relational-databases#federation-one-database-per-feature\">Federation</a>.</li>\n<li><strong>Sharding:</strong> split <code>sales_rank</code> across databases by <code>category_id</code>. Every query names one category, so each read touches exactly one shard. See <a href=\"/learn/relational-databases#sharding-splitting-one-table-across-databases\">Sharding</a>.</li>\n<li><strong>Denormalization:</strong> store the product name, image URL and price in the ranking rows, so the read path needs no lookup in the catalog. The cost is keeping those copies in sync. See <a href=\"/learn/relational-databases#denormalization\">Denormalization</a>.</li>\n<li><strong>SQL tuning:</strong> benchmark, find slow queries, and make sure the main query is served from the <code>by_category</code> index alone. See <a href=\"/learn/relational-databases#sql-tuning\">SQL tuning</a>.</li>\n</ul>\n<p><strong>Moving to NoSQL.</strong> The read path needs exactly one operation: \"give me the list for this key\". A key-value store such as DynamoDB or Redis, holding each category's top list as one value, fits that well. See the trade-offs below and <a href=\"/learn/nosql-databases#sql-or-nosql-making-the-choice\">SQL or NoSQL: making the choice</a>.</p>","headings":[{"id":"step-4-scale-the-design","title":"Step 4: Scale the design","depth":3},{"id":"the-read-path-40000-requests-a-second","title":"The read path: 40,000 requests a second","depth":4},{"id":"the-write-path-the-ranking-database-and-the-raw-sales-data","title":"The write path: the ranking database and the raw sales data","depth":4},{"id":"consistency-and-availability","title":"Consistency and availability","depth":4},{"id":"sql-scaling-patterns-if-the-database-grows","title":"SQL scaling patterns, if the database grows","depth":4}]},{"id":"trade-offs-and-follow-up-questions","title":"Trade-offs and follow-up questions","html":"<h3 id=\"trade-offs-and-follow-up-questions\">Trade-offs and follow-up questions</h3>\n<p><strong>Hourly batch recompute or streaming top-K?</strong> A <strong>streaming</strong> design processes each sale as it arrives: a stream processor reads sales from a log such as Kafka, keeps a running count per (category, product) for the sliding window, and updates a sorted set per category, much like the <a href=\"/learn/design-gaming-leaderboard#skip-lists-and-redis-sorted-sets\">leaderboard design</a>. Rankings would then be seconds old instead of an hour. The costs are real: the processor must hold a week of windowed state, handle late and duplicate events, and recover that state after a crash. See <a href=\"/learn/event-streaming#delivery-semantics\">Delivery semantics</a>. With an hourly freshness requirement, I'd pick the batch job: it's simpler, cheaper, and correct by construction because each run starts from the log. If the business later wants minute-level freshness for the top few products in each category, add a small streaming job for just those and keep the batch job as the source of truth. That's the <a href=\"/learn/batch-processing#the-lambda-architecture\">Lambda architecture</a> in miniature, with the cost of maintaining the counting logic twice.</p>\n<p><strong>Full recompute or incremental window?</strong> Full recompute reads about 10 GB an hour and fixes its own mistakes. Incremental reads about 58 MB an hour but carries errors forward. At a one-week window I'd start with full recompute; with a longer window or much more traffic, switch to incremental with a daily rebuild.</p>\n<p><strong>MapReduce, Spark or the warehouse?</strong> MapReduce writes every intermediate result to disk between passes. Spark keeps them in memory and expresses both passes in one job. A warehouse expresses both in one SQL query. At 10 GB a run, I'd pick the warehouse or Spark; the two-pass MapReduce is the clearest way to explain the logic, which is why it's worth knowing for the interview.</p>\n<p><strong>SQL table or key-value lists?</strong> A SQL table supports several query shapes (by category, by product, ad hoc checks) and transactional publishing. A key-value store with one value per category gives a single fast read per request and scales out easily, but answering \"what's the rank of product X\" needs a second structure keyed by product. Since the cache already holds the per-category lists, I'd keep SQL as the durable store and treat the cache as the key-value layer.</p>\n<p><strong>Top N only, or every product?</strong> Storing the top 100 per category keeps the table at about 10 MB. Storing every product (up to 20 million rows) costs about 2 GB and a second index, and lets each product page show its rank, as Amazon's help page says its product pages do. That's cheap, so I'd store everything if product pages need it.</p>\n<p><strong>How fresh do popular products need to be?</strong> The assumptions say popular products might need updating more often. One option is to rerun pass 2 every 10 minutes for the busiest categories, using the hourly counts plus a quick count of the current partial hour. The other is the streaming add-on above. Ask first what \"more often\" is for: catching a viral product needs minutes, while reporting is fine with an hour.</p>","headings":[{"id":"trade-offs-and-follow-up-questions","title":"Trade-offs and follow-up questions","depth":3}]},{"id":"check-yourself","title":"Check yourself","html":"<h3 id=\"check-yourself\">Check yourself</h3>\n<details>\n<summary>The product team wants the window extended from 7 days to 30 days. What happens to the hourly job, and what would you change?</summary>\n<p>Each full recompute grows from about 233 million transactions (about 10 GB) to the whole month's 1 billion (about 42 GB), read every hour. That still fits a modest cluster, but nearly all of the work repeats the previous hour's.</p>\n<p>This is the point to switch to the incremental window: compute pass 1 once per hour, keep the 720 hourly count files, and slide a running total forward by adding the newest hour and subtracting the expired one. Each run then reads about 58 MB of new data plus the running total. Rebuild the running total from the hourly files once a day so errors can't accumulate.</p>\n</details>\n<details>\n<summary>A seller complains that their product ranks #1 in \"Phone Cases\" even though most buyers returned it. Why did this happen, and how would you fix it?</summary>\n<p>The job counts units from the sales log, and returns don't appear in that log, so every unit sold counts whether it was kept or not.</p>\n<p>Log returns as events with a negative quantity and let pass 1 sum them like any other line. Counting a return in the hour it happened is simplest, but it can then land in a window that doesn't contain its sale, so clamp each total at zero. Ranking by distinct buyers who kept the product is another option worth raising with the product team.</p>\n</details>\n<details>\n<summary>Every hour, a few seconds after the new ranking is published, the read replicas' CPU spikes and some requests time out. What's going on?</summary>\n<p>It's a cache stampede. The cached lists probably all expire, or are all deleted, when the new run is published, so for a moment every request misses and thousands of identical queries hit the replicas at once.</p>\n<p>Have the Sales Rank Service write the new lists into the cache as part of publishing, so the cache already holds the new answer before readers switch. Keep TTLs as a safety net, with random jitter so keys don't expire together. Request coalescing, where only one request per key goes to the database on a miss while the others wait for it, also helps.</p>\n</details>\n<details>\n<summary>Product pages should show \"#N in Category\" for every product, not just the top 100. What changes in the job, the table and the read path?</summary>\n<p>The job's pass 2 must keep every product instead of stopping at N, so the per-mapper pruning goes away and the shuffle moves all of the (category, product) totals: up to 20 million rows. That's still small.</p>\n<p>The table grows to up to 20 million rows per run, about 2 GB, and the <code>by_product</code> index becomes essential, because the product page asks \"what are product X's ranks?\" The read path gets a second endpoint, such as <code>GET /api/v1/products/50/ranks</code>. Its traffic is spread over 10 million products, so the cache hit rate is lower than for category lists. Cache the popular products, and let the read replicas handle the long tail.</p>\n</details>\n<details>\n<summary>In pass 2, why is it safe for each map task to keep only its local top 100 per category, while the same trick in pass 1 would give wrong answers?</summary>\n<p>After pass 1, each (category, product) pair appears exactly once, with its full total for the week. If a product isn't in the top 100 among the entries one map task holds, then at least 100 products in that same category have higher totals. So it can't be in the overall top 100 either, and dropping it changes nothing.</p>\n<p>In pass 1, a product's units are still spread across many map tasks, one partial count per log file. A product with modest sales in every file might look unimportant in each task yet have the largest total once all its partial counts are added. Pruning there would drop real best sellers.</p>\n</details>\n<details>\n<summary>Estimate how much memory the cache needs to hold the first page of every category, and whether a single cache server is enough.</summary>\n<p>There are 1,000 categories, and the first page is about 2 KB, so 1,000 × 2 KB = 2 MB. Even ten pages per category is only 20 MB. Memory isn't the constraint; one server could hold this thousands of times over.</p>\n<p>The constraints are request rate and availability. Whatever the CDN doesn't absorb of the 120,000 requests a second at peak goes to the cache. Run two or three cache nodes, each holding the full set, so losing one doesn't send a burst of misses to the database. With data this small, replicate it to every node instead of splitting it.</p>\n</details>\n<h3 id=\"further-reading\">Further reading</h3>\n<ul>\n<li><a href=\"https://www.amazon.com/gp/help/customer/display.html?nodeId=GGGMZK378RQPATDJ\" target=\"_blank\" rel=\"noopener noreferrer\">Amazon Best Sellers Rank (Amazon customer service)</a>: Amazon's own short description of what its Best Sellers Rank reflects and why category lists exist. The <a href=\"https://www.amazon.co.uk/gp/help/customer/display.html?nodeId=GGGMZK378RQPATDJ\" target=\"_blank\" rel=\"noopener noreferrer\">UK version</a> of the page says it's updated hourly.</li>\n<li><a href=\"https://research.google/pubs/mapreduce-simplified-data-processing-on-large-clusters/\" target=\"_blank\" rel=\"noopener noreferrer\">MapReduce: Simplified Data Processing on Large Clusters</a>: Jeffrey Dean and Sanjay Ghemawat's 2004 OSDI paper, the original description of the map, shuffle and reduce model the ranking job uses.</li>\n<li><a href=\"https://nightlies.apache.org/flink/flink-docs-stable/docs/dev/datastream/operators/windows/\" target=\"_blank\" rel=\"noopener noreferrer\">Apache Flink: Windows</a>: a clear explanation of tumbling and sliding windows, useful if you build the streaming version.</li>\n<li><a href=\"https://docs.aws.amazon.com/redshift/latest/mgmt/welcome.html\" target=\"_blank\" rel=\"noopener noreferrer\">What is Amazon Redshift?</a>: AWS's overview of its data warehouse, an example of the analytics database in step 4.</li>\n<li><a href=\"https://gist.github.com/jboner/2841832\" target=\"_blank\" rel=\"noopener noreferrer\">Latency numbers every programmer should know</a>: Jonas Bonér's widely shared table, the source of the memory, SSD and disk read times quoted above.</li>\n</ul>","headings":[{"id":"check-yourself","title":"Check yourself","depth":3},{"id":"further-reading","title":"Further reading","depth":3}]}]}