Docs: explain Downsample transformation sampling methods

[landon-posthog]

Changes

The Downsample transformation docs page is auto-generated from the template, so its two Sampling method options — Distinct ID aware sampling and Random sampling — appeared in the config table with no explanation of what they actually do.

This adds a hand-written MDX override (linked by templateId, same mechanism as drop-events.mdx) that keeps the live <TemplateParameters /> config table and adds:

• What each sampling method does, and that Distinct ID aware (the default) keeps whole users — 100% of events for ~N% of users — so per-user funnels/paths/replays stay intact, vs Random which drops events across all users and leaves gaps in individual streams.
• That the hash is stable across percentage changes.
• A caution that downsampling is lossy at ingestion and charts show the reduced numbers, with a pointer to insight-level sampling for query-time sampling that is auto-adjusted.
• Installation, testing, and FAQ sections, plus a link to the transformation source code.

Why: A user hit the Distinct ID aware sampling option in-app and could find no documentation explaining whether it would leave holes in a single user's data. The behavior is only discoverable by reading the plugin source.

Checklist

• I've read the docs and/or content style guides.
• Words are spelled using American English
• Use relative URLs for internal links
• I've checked the pages added or changed in the Vercel preview build
• If I moved a page, I added a redirect in vercel.json

---

Created with PostHog from a Slack thread

[github-actions]

Deploy preview

Status	Details	Updated (UTC)
🟢 Ready	View preview	Jul 01, 2026 07:24PM

[github-actions]

Vale prose linter → found 6 errors, 11 warnings, 0 suggestions in your markdown

Full report → Copy the linter results into an LLM to batch-fix issues.

Linter being weird? Update the rules!

contents/docs/cdp/transformations/downsampling-plugin.mdx — 6 errors, 11 warnings, 0 suggestions

Line	Severity	Message	Rule
2:8	warning	'Downsample' is a possible misspelling.	PostHogBase.Spelling
17:57	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
17:235	warning	'downsampling' is a possible misspelling.	PostHogBase.Spelling
19:147	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
27:17	warning	'Downsample' is a possible misspelling.	PostHogBase.Spelling
29:39	warning	'downsampling' is a possible misspelling.	PostHogBase.Spelling
43:282	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
45:169	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
51:221	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
55:28	warning	'downsampled' is a possible misspelling.	PostHogBase.Spelling
55:44	warning	'downsample' is a possible misspelling.	PostHogBase.Spelling
59:209	warning	'downsampling' is a possible misspelling.	PostHogBase.Spelling
65:17	warning	'downsampling' is a possible misspelling.	PostHogBase.Spelling
72:4	warning	'FAQ' heading should be in sentence case, and product names should be capitalized.	PostHogBase.SentenceCase
74:10	warning	'downsampling' is a possible misspelling.	PostHogBase.Spelling
76:6	warning	'Downsampled' is a possible misspelling.	PostHogBase.Spelling
80:126	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash

[github-actions]

Bundle report

Total JS (gzip)

6.33 MiB (no change)

Eager graph (static-import closure per entrypoint)

Entrypoint	Eager size	Budget	Modules
✅ app	24.21 MiB (no change)	report-only	5517

Largest modules in the app closure

Module	Size
css ./node_modules/.pnpm/css-loader@5.2.7_webpack@5.101.3/node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[1]!./node_modules/.pnpm/postcss-loader@4.3.0_postcss@8.5.6_webpack@5.101.3/node_modules/postcss-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[2]!./src/styles/global.css	713.8 KiB
./src/components/Stickers/Stickers.tsx	696.4 KiB
./.cache/caches/gatsby-plugin-mdx/mdx-scopes-dir/31a094f140f119e73085d847ae81b99b.js + 2 modules	573.8 KiB
./node_modules/.pnpm/@radix-ui+react-icons@1.3.2_react@18.3.1/node_modules/@radix-ui/react-icons/dist/react-icons.esm.js	481.4 KiB
./node_modules/.pnpm/@codemirror+view@6.38.2/node_modules/@codemirror/view/dist/index.js	458.1 KiB
./node_modules/.pnpm/rehype-raw@7.0.0/node_modules/rehype-raw/lib/index.js + 29 modules	395.1 KiB
./node_modules/.pnpm/@posthog+icons@0.36.6_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.cjs.js	364.8 KiB
./node_modules/.pnpm/@posthog+icons@0.36.6_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.es.js	354.8 KiB
./src/hooks/useCustomers.tsx + 54 modules	353.9 KiB
./node_modules/.pnpm/react-markdown@8.0.7_@types+react@16.14.66_react@18.3.1/node_modules/react-markdown/lib/react-markdown.js + 88 modules	351.4 KiB
./node_modules/.pnpm/cloudinary-core@2.14.0_lodash@4.17.21/node_modules/cloudinary-core/cloudinary-core.js	281.9 KiB
./src/components/ProductComparisonTable/index.tsx + 116 modules	267.6 KiB
./node_modules/.pnpm/@codesandbox+sandpack-react@2.20.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@codesandbox/sandpack-react/dist/index.mjs	266.6 KiB
./node_modules/.pnpm/d3@7.9.0/node_modules/d3/src/index.js + 208 modules	247.4 KiB
./src/components/Pricing/PricingSlider/Slider.tsx + 87 modules	239.9 KiB

---

Eager-graph budgets are report-only until a baseline is established. Sizes are gzip of public/**/*.js; eager size is webpack module source bytes.