ivankelly commented on a change in pull request #1466: Topic compaction
documentation
URL: https://github.com/apache/incubator-pulsar/pull/1466#discussion_r190833665
##########
File path: site/docs/latest/cookbooks/compaction.md
##########
@@ -0,0 +1,113 @@
+---
+title: Topic compaction cookbook
+tags: [admin, clients, compaction]
+---
+
+Pulsar's [topic
compaction](../../getting-started/ConceptsAndArchitecture#compaction) feature
enables you to create **compacted** topics in which older, "obscured" entries
are pruned from the topic, allowing for faster reads through the topic's
history (which messages are deemed obscured/outdated/irrelevant will depend on
your use case).
+
+To use compaction:
+
+* You must manually [trigger](#trigger) compaction using the Pulsar
administrative API. This will both run a compaction operation *and* mark the
topic as a compacted topic.
+* Your {% popover consumers %} must be [configured](#config) to read from
compacted topics (or else the messages won't be properly
read/processed/acknowledged).
+
+In Pulsar, topic compaction takes place on a *per-key basis*, meaning that
messages are compacted based on their key. For the stock ticker use case, the
stock symbol---e.g. `AAPL` or `GOOG`---could serve as the key.
+
+## When should I use compacted topics?
+
+The classic example of a topic that could benefit from compaction would be a
stock ticker topic through which {% popover consumers %} can access up-to-date
values for specific stocks. On a stock ticker topic you only care about the
most recent value of each stock; "historical values" don't matter, so there's
no need to read through outdated data when processing a topic's messages. For
topics where older values are important, for example when you need to process
long series of messages in order, compaction is unnecessary and possibly even
harmful.
Review comment:
The same topic can serve both usecases with compaction. We don't delete the
old history when we compact. Compaction isn't to save space, but rather to
allow clients to catch up quickly.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
With regards,
Apache Git Services
