`)
- Links (``)
- Lists (`` / `` / `- `)
### Markdown vs. HTML
- Prefer Markdown syntax over HTML when possible for better readability and maintainability.
- Use HTML only when Markdown doesn't provide the necessary functionality.
- When mixing Markdown and HTML, ensure proper spacing and formatting. Preview the rendered page locally.
## Callouts
CockroachDB docs use three classes of "callouts," which are highlighted blocks of text: tips, notes, and warnings.
- To insert a **tip**, use the following code:
~~~
{{site.data.alerts.callout_success}}
tip text goes here
{{site.data.alerts.end}}
~~~
- To insert a **note**, use the following code:
~~~
{{site.data.alerts.callout_info}}
note text goes here
{{site.data.alerts.end}}
~~~
- To insert a **warning**, use the following code:
~~~
{{site.data.alerts.callout_danger}}
warning text goes here
{{site.data.alerts.end}}
~~~
## Images
Use the following HTML and Liquid to include an image in a Markdown page:
~~~ html
~~~
## Videos
Use the following Liquid to include an embedded video in a Markdown page:
~~~ md
{% include_cached youtube.html video_id="
" [widescreen=true] %}
~~~
The `video_id` parameter is required and is whatever is after the `?v=` portion of the URL. If the URL to the video you wish to embed is `https://www.youtube.com/watch?v=5kiMg7GXAsY`, for example, then the value of `video_id` should be `5kiMg7GXAsY`. The `widescreen` parameter is optional and meant for videos with wide banners such as our video on [Foreign Key Constraints](https://www.youtube.com/watch?v=5kiMg7GXAsY).
You can optionally pass in a start time to the `video_id` parameter to make the video start at a specific timestamp. The below example embeds the [How to Create Tables with Foreign Keys in SQL](https://www.youtube.com/watch?v=mFQk1VsIkZA) video and starts playing it at 25 seconds:
~~~ md
{% include_cached youtube.html video_id="mFQk1VsIkZA?start=25" %}
~~~
## Versioning
Use version tags to highlight new features and version references to link to specific CockroachDB versions in documentation.
### Version tags
Version tags inform users of new and updated features in CockroachDB, and could motivate users to upgrade to the latest major or patch version of CockroachDB. Version tags also help us identify new and updated features that we can call out in [our GA release notes](https://cockroachlabs.atlassian.net/wiki/spaces/ED/pages/402718726/GA+Release+Checklist).
To add a version tag, use the following Liquid tag:
~~~
{% include_cached new-in.html version="v22.1" %}
~~~
Note: If using a version tag inside of a Markdown table, use `New in vXX.Y:` or `New in vXX.Y.Z:` instead.
Put version tags at the beginning of a paragraph, sentence, or description in a table cell.
If a feature is new in a GA release, use the major release number for the release version tag (e.g., `{% include_cached new-in.html version="v21.2" %}`).
If a feature has been backported to a previous version in a patch release, use the patch release number for the release version tag (for example, `{% include_cached new-in.html version="v21.2.10" %}`).
Version tags should only refer to the version of the docset that contains them. For example, the version tag `{% include_cached new-in.html version="v21.1.9" %}` should only be on pages in `v21.1` directories.
### Version references
To refer to a static version of CockroachDB:
~~~
{{site.versions["v22.2"]}}
~~~
To dynamically refer to the stable version of CockroachDB, as determined each time the site is built:
~~~
{{site.versions["stable"]}}
~~~
**Warning**: If you use a `stable` link on a versioned page which is for a previous version, the link points to a different version of CockroachDB than the version the page documents. Similarly, if you use a `stable` link on a page for the current version and then a new version is added, the link points to a different version than the version the page documents. If this is a problem, use one of the following methods instead.
Pages that document CockroachDB itself exist within subdirectories that represent major versions. To refer to a page's major version (for example, v22.2), which matches its top-level subdirectory within the docs repo:
~~~
{{page.version.version}}
~~~
A patch release version of CockroachDB receives updates as patches. To refer to a page's current patch version (for example, v22.1.7):
~~~
{{ page.release_info.name }}
~~~
## Include files
There are [basic](#basic-include-file-usage) and [advanced](#advanced-include-file-usage) methods for using include files. Use the basic method unless you are sure you need the advanced.
### Basic include file usage
The basic method for using an include file is:
1. Find (or create) a block of content that you want to make appear on two or more different pages.
1. Create a new file in the subdirectory of the `_includes` directory associated with the product you are working on. For example, if you are working on CockroachDB Self-Hosted v22.1, the directory will be `_includes/v22.1/`. If you are working on CockroachDB Dedicated, it will be `_includes/cockroachcloud`. If the include text is not version- or product-specific, put it in the `common` directory.
1. In the pages where you want the included content to appear, add an `include` tag like one of the following: for CockroachDB Self-Hosted, `{% include {{page.version.version}}/some/shared-file.md %}`; for CockroachDB Dedicated, `{% include cockroachcloud/some/shared-file.md %}`.
The contents of `shared-file.md` will now appear on all of the pages where you added the `include` tag.
### Advanced include file usage
#### Different content depending on page name
There may be cases where the content of the include file will need to vary slightly depending on what pages that content is being shared into. For example, while working on [cockroachlabs/docs#12216](https://github.com/cockroachlabs/docs/pull/12216), I needed a way to:
- Have text be a link on the [Known Limitations](https://www.cockroachlabs.com/docs/stable/known-limitations) page.
- Have that same text _not_ be a link on the [Cost-Based Optimizer](https://www.cockroachlabs.com/docs/stable/cost-based-optimizer) page (since it would be a self-referring link).
The way to do this in Jekyll (with its templating language Liquid) is to add the following content to an include file that is shared into both pages:
{% if page.name == "cost-based-optimizer.md" %} Locality-optimized search {% else %} [Locality-optimized search](cost-based-optimizer.html#locality-optimized-search-in-multi-region-clusters) {% endif %} only works for queries selecting a limited number of records (up to 10,000 unique keys). Also, it does not yet work with [`LIMIT`](limit-offset.html) clauses.
The syntax is a little hard to read inline, but based on some experimenting it appears that it _must_ be written as one line so as not to introduce line breaks in the resulting text.
Formatted for easier reading, the template code looks like:
```
{% if page.name == "cost-based-optimizer.md" %}
Locality-optimized search
{% else %}
[Locality-optimized search](cost-based-optimizer.html#locality-optimized-search-in-multi-region-clusters)
{% endif %}
```
#### Remote includes
Sometimes, you need to include files that are maintained in other places than the `cockroachlabs/docs` repo but referenced in our docs. The `remote_include` tag is used for this. We most often use this tag for code samples, which are maintained in various repos.
For code samples, you usually want to show only part of a larger file to highlight a specific technique, or due to length considerations.
To accomplish this, the `remote_include` tag lets you pass arguments (usually named `START {text}` and `END {text}` by convention) that pull in the text of the remote file between `START {text}` and `END {text}`.
For example, the file `movr-flask-application.md` (which becomes the page [Develop a Global Web Application](https://www.cockroachlabs.com/docs/v22.1/movr-flask-application.html)) has the following `remote_include`:
```
{% remote_include https://raw.githubusercontent.com/cockroachlabs/movr-flask/v2-doc-includes/dbinit.sql ||-- START database ||-- END database %}
```
If you browse to the `dbinit.sql` file, you will find the following SQL code block that uses those start and end tags:
```
-- START database
CREATE DATABASE movr PRIMARY REGION "gcp-us-east1" REGIONS "gcp-us-east1", "gcp-europe-west1", "gcp-us-west1";
-- END database
```
For more information about the `remote_include` tag, see the README in the [jekyll-remote-include](https://github.com/cockroachdb/jekyll-remote-include) repo.
### Filter tabs
Use filter tabs to create navigation between related pages. The [`filter-tabs.md`](https://github.com/cockroachlabs/docs/blob/main/src/current/_includes/filter-tabs.md) include generates tabs that link to different pages.
**Note:** Filter tabs link to different URLs/pages, not tabs within a single page.
**Setup process:**
1. Identify pages for filter tabs and note their HTML filenames (for example, `install-cockroachdb-mac.html`).
1. Create an include file in `_includes//filter-tabs/` with this structure:
```liquid
{% assign tab_names_html = "Tab 1;Tab 2;Tab 3" %}
{% assign html_page_filenames = "page1.html;page2.html;page3.html" %}
{% include filter-tabs.md tab_names=tab_names_html page_filenames=html_page_filenames page_folder= %}
```
1. Include the filter tabs on each target page: `{% include /filter-tabs/.html %}`
### Technical limitations of include files
Include files have the following technical limitations:
- Cannot be used in [Markdown tables](#markdown-tables)
- Remote includes cannot reference local includes
- Include files with paragraphs followed by code blocks may not render correctly in all contexts
## Tabs
To allow your reader to select from two or more versions of on-page content, use a tabset. This might be appropriate for:
- Install procedurals with different steps for the different supported platforms (like macOS, Windows, Linux).
- Reference material where the Enterprise and non-Enterprise versions of a feature differ.
- Demonstrating how to connect from an example application in each supported programming language (like Python, C++, Java, etc.).
To add tabs to your copy, you first define the tabset for use later on the page, then you declare each tab's content within each tab.
To define the tabset:
```
```
This example defines two tabs (named `macOS` and `Windows`) and defines a unique `data-scope` for each (`macos-install-steps` and `windows-install-steps` respectively).
Then, to declare the content within each tab:
```
1. To install CockroachDB on macOS, first you need to ...
...
1. To install CockroachDB on Windows, first you need to ...
...
## This section outside of tabs
```
Now the user can freely switch between the `macOS` and `Windows` tabs as needed.
Tip: Do your tabs share a lot of common content betwen them? Tabs are often a great place to make use of [include files](#include-files)!
### Linking into tabbed content
To link to content that is contained within a tab, add the `filter` component to your link, specifying the `data-scope` you provided in your tabset definition. You can do this in the following two ways:
- To link to the top of a target page, with a specific tab selected:
```
[Core changefeeds](create-and-configure-changefeeds.html?filters=core)
```
This takes us to the top of `create-and-configure-changefeeds.html` and ensures the tab matching `data-scope: core` is selected. See [Create and Configure Changefeeds](https://www.cockroachlabs.com/docs/stable/create-and-configure-changefeeds.html?filters=core) to see this in action.
- For linking to a header contained within a tabset:
```
[Create with column families](changefeeds-on-tables-with-column-families.html?filters=core#create-a-core-changefeed-on-a-table-with-column-families)
```
This takes us directly to the `create-a-core-changefeed-on-a-table-with-column-families` header, within the `data-scope: core` tab. See [Create a Core changefeed on a table with column families](https://www.cockroachlabs.com/docs/stable/changefeeds-on-tables-with-column-families.html?filters=core#create-a-core-changefeed-on-a-table-with-column-families) to see this in action.
Considerations:
- If you intend to link to a header present on two or more tabsets on the same page, the header targets must be uniquely named. If you require identical header names, use explicit, unique HTML anchor names for each (in form `` as shown under [Links](#links).
- For the first-defined tab, specifying its `filter` value in a link is functionally the same as omitting it. For all other tabs, the explicit filter name is required. You can think of this first tab as the "default" tab in this context: if not otherwise specificed, Jekyll will always open with the first tab's contents displayed.
## Comments
There may be situations that require adding an explanation below a piece of content or to temporarily suppress content within a page. In those situations, use [Liquid comments](https://shopify.github.io/liquid/tags/template/#comment).
Page source:
```
This sentence is visible!
{% comment %}
This sentence is not visible!
{% endcomment %}
This sentence is visible except for a single commented word: {% comment %}CockroachDB{% endcomment %}
```
Final page HTML:
```
This sentence is visible!
This sentence is visible except for a single commented word:
```
Do not use HTML comments (``), because HTML comments are visible in the page's HTML source code in production. Additionally, any HTML comment content must be processed by the Liquid parser, so any Liquid within an HTML comment is still processed and can produce errors, such as a broken include or broken link.
### TODOS
If you have future work to do in a particular file, simply add `TODO` or a `FIXME` inside of a comment. A colon after `TODO` or `FIXME` is optional.
Examples:
```
{% comment %}
TODO clean up the style guide
{% endcomment %}
```
```
{% comment %}
FIXME: Update example SQL commands
{% endcomment %}
```
Many popular code editors feature extensions that can highlight `TODO`s across the repository. One such extension is [Todo Highlight](https://marketplace.visualstudio.com/items?itemName=wayou.vscode-todo-highlight).
---
## File: StyleGuide.md
# Style Guide
The following guidance is provided to benefit CockroachDB docs authors and reviewers by reflecting past style decisions, and to benefit readers by promoting consistency and readability across our content.
Included in this guide:
- [Style and tone](#style-and-tone)
- [Perspective and voice](#perspective-and-voice)
- [Prescriptive writing](#prescriptive-writing)
- [Speculation and feature support](#speculation-and-feature-support)
- [Latinisms](#latinisms)
- [Word usage guidelines](#word-usage-guidelines)
- [CockroachDB products](#cockroachdb-products)
- [CockroachDB versions](#cockroachdb-versions)
- [Third-party products](#third-party-products)
- [AI](#ai)
- [Inclusivity](#inclusivity)
- [Avoid ableist language](#avoid-ableist-language)
- [Avoid unnecessarily gendered language](#avoid-unnecessarily-gendered-language)
- [Write diverse and inclusive examples](#write-diverse-and-inclusive-examples)
- [Avoid unnecessarily violent language](#avoid-unnecessarily-violent-language)
- [Write accessible documentation](#write-accessible-documentation)
- [Write about features and users in inclusive ways](#write-about-features-and-users-in-inclusive-ways)
- [Capitalization and punctuation](#capitalization-and-punctuation)
- [Capitalization rules](#capitalization-rules)
- [Punctuation rules](#punctuation-rules)
- [Vale](#vale)
- [File conventions](#file-conventions)
- [Content types](#content-types)
- [Concept](#concept)
- [Task](#task)
- [Reference](#reference)
- [Guide](#guide)
- [Page components](#page-components)
- [Code](#code)
- [Callouts](#callouts)
- [Images](#images)
- [Videos](#videos)
- [Include files](#include-files)
- [Links](#links)
- [GitHub links](#github-links)
- [External links](#external-links)
- [Page sections](#page-sections)
- [Before you begin](#before-you-begin)
- [Known limitations](#known-limitations)
- [See also](#see-also)
For Markdown-specific syntax and formatting guidelines, refer to the [Markdown Guide](MarkdownGuide.md).
## Style and tone
CockroachDB docs should be helpful, humble, positive, friendly, and free from hyperbolic language.
### Perspective and voice
For instructions, use the imperative present tense, aka "[imperative mood](https://www.grammar-monster.com/glossary/imperative_mood.htm)." The second-person subject ("you") is implied and can be omitted.
**Examples:**
- Run `cockroach start`.
- Click **Next**.
In tutorials, where a conversational tone is sometimes helpful, use the second person ("you").
**Examples:**
- In this tutorial, you'll start with a new cluster, so stop and clean up any existing clusters.
- After you create the database, insert some rows.
In page titles and headings, use the imperative mood to name a task. Do not use the gerund form or a noun phrase.
- **Avoid:** Managing Users
**Avoid:** User Management
**Prefer:** Manage Users
Do not use "we" to refer to "CockroachDB" or "Cockroach Labs".
- **Avoid:** We support changefeeds.
**Prefer:** CockroachDB supports changefeeds.
- **Avoid:** We recommend ...
**Prefer:** Cockroach Labs recommends ...
### Prescriptive writing
Write in a prescriptive style that clearly guides the user. The user should feel confident and supported, without having to infer meaning or make too many decisions on their own.
Use active instead of passive voice.
- **Avoid:** Each parameter should be set explicitly.
**Prefer:** Set each parameter explicitly.
- **Avoid:** Additional options can be specified.
**Prefer:** You can specify additional options.
Use concise, direct language. Cut unnecessary words unless a conversational tone is intentional (for example, in tutorials). If a feature or concept is difficult to describe clearly or concisely, consider using an [example](#examples) or [image](#images) to complement the text.
- **Avoid:** Be mindful of the possibility that you might encounter a different result, depending on the specifics of your configuration, so you might want to do some testing first to see what happens.
**Prefer:** Run tests to verify that you get the expected result for your configuration.
- **Avoid:** `table_name`: This parameter is used to specify the name of the table you want to modify.
**Prefer:** `table_name`: The name of the table to modify.
Provide guidance rather than leave decisions to the user. For example, phrases like "change what you need" or "modify the relevant settings" may raise questions like "What would I need to change?" and "Which settings are relevant?". When user discretion is required, be as explicit as possible to reduce ambiguity and cognitive load.
- **Avoid:** Increase the threshold as needed.
**Prefer:** Increase the threshold until you see a performance improvement.
- **Avoid:** Define additional settings as desired.
**Prefer:** Depending on your configuration, you may need to define additional settings. For example, ...
- **Avoid:** Edit the profile using your preferred text editor.
**Prefer:** Edit the profile in a text editor.
Avoid vague time estimates. Provide a specific timeframe when possible.
- **Avoid:** You should set the grace period to at least a few minutes.
**Prefer:** Set the grace period to at least 5 minutes.
- **Avoid:** This should take a few moments. When finished, click **Next**.
**Prefer:** When finished, click **Next**.
Do not use contractions when giving a technical description or instruction.
- **Example:** You cannot change primary key using `ALTER TABLE`.
- **Example:** If you leave versioned binaries on your servers, you do not need to do anything.
Do not use "please" when giving an instruction, except when asking the user to go outside the scope of the task (for example, contacting Cockroach Labs or filing a support issue).
- **Example:** If you need assistance, please contact [support](https://support.cockroachlabs.com/).
- **Avoid:** Please click on the **Next** button.
**Prefer:** Click **Next**.
Do not use language that could be read as presumptuous or condescending.
- **Avoid:** If you aren't willing to do this for some reason, ...
**Prefer:** If this is not possible, ...
- **Avoid:** Monitoring the cluster is simple.
**Prefer:** Monitor the cluster with the following tools:
### Speculation and feature support
Avoid forward-looking language when writing about supported syntax and behavior. Do not suggest that a feature may or may not be added in a future release. Avoid words like "yet" and "currently", and do not reference the internal product roadmap.
- **Avoid:** CockroachDB does not yet support column-level privileges. This is planned for a future release.
**Prefer:** CockroachDB does not support column-level privileges.
### Latinisms
For readability, avoid Latinisms.
- **Avoid:** Select a deployment option, e.g., {{ site.data.products.standard }} or {{ site.data.products.advanced }}.
**Prefer:** Select a deployment option such as {{ site.data.products.standard }} or {{ site.data.products.advanced }}.
## Word usage guidelines
This section logs decisions about dictionary words to use and avoid. Add specific guidelines we decide as a team to this section. Refer also to [Technical terminology](#technical-terminology) for technical terms that may not be in a dictionary.
### CockroachDB products
- Use the following combinations of `CockroachDB` and Liquid variables to display product names on docs pages. Liquid variables cannot be used in Markdown front-matter, file names, or non-Markdown files. In those cases, write the product names manually.
- **CockroachDB Cloud** : `CockroachDB {{ site.data.products.cloud }}`
- **CockroachDB Basic** : `CockroachDB {{ site.data.products.basic }}`
- **CockroachDB Standard** : `CockroachDB {{ site.data.products.standard }}`
- **CockroachDB Advanced** : `CockroachDB {{ site.data.products.advanced }}`
- **CockroachDB self-hosted cluster** : `CockroachDB {{ site.data.products.core }} cluster`
- Use the full product name on its first occurrence on a page. You may subsequently shorten product names to "Basic", "Advanced", or "Cloud", unless this would introduce ambiguity (for example, on long pages where product names might be separated by multiple paragraphs).
- Do not shorten "CockroachDB" to "CRDB".
- Use "`cockroach`" to refer to the CockroachDB binary.
- **Avoid:** Cockroach process
**Prefer:** `cockroach` process
### CockroachDB versions
Refer to CockroachDB versions as `vxx.x.x` (for example, `v21.1.8`). Do not use `version xx.x.x`.
For version ranges, use `to` between numbers (for example, `v22.1.0 to v22.1.4`). Do not use a dash. Refer to [Punctuation rules](#punctuation-rules).
Refer to "earlier" and "later" versions, rather than "lower" and "higher" versions. For example, `CockroachDB v25.3 and earlier`.
### Third-party products
In general, align third-party branding with that brand's usage. Do not use the shortened versions of product names.
| Avoid | Prefer |
|----------|------------|
| Postgres | PostgreSQL |
| K8s | Kubernetes |
### "Directory" vs. "folder"
- Use "directory" to refer to a filesystem directory, either locally or in a VM. For example, `Compress the directory into a .zip archive.`
- Use "folder" to refer to a folder within a UI, such as a web UI or an IDE. For example, `Create a folder in your CockroachDB Cloud organization.`
### "Legacy" vs. "deprecated"
- Use "legacy" only for our own earlier products, features, or workflows to signal that a newer option is preferred. Avoid using "legacy" as a pejorative; if no preference is intended, say "earlier" or "previous". Do not use "legacy" to refer to competitors' products.
- Prefer "deprecated" when there is an approved plan for end of support and removal. If deprecation is not approved but guidance is needed, you may call the previous option "legacy".
### "In" vs. "on" a cluster
Use "in a cluster" when referring to elements that form the cluster itself.
**Examples:**
- Nodes in the cluster
- Ranges in the cluster
Use **on a cluster** when referring to workloads, services, or databases that run on the cluster's infrastructure.
**Examples:**
- Databases on the cluster
- Jobs running on the cluster
### AI
Write "AI" without periods. Not "A.I."
You don't need to precede the usage of the term "AI" with its elaboration (e.g. "Artificial Intelligence (AI).") Any reader will know what AI is.
When describing "AI tools," "AI agents," or "AI assistants" (etc.) in the context of integrating with CockroachDB, precede introductory instances of these terms with the word "your."
- **Avoid:** The MCP server enables AI tools to access a cluster.
- **Prefer:** The MCP server enables your AI tools to access a cluster.
This is a request from Cockroach Labs' legal team. The idea is to remind the reader that these tools are not Cockroach Labs', and so any mistaken/detrimental use of these tools is not Cockroach Labs' responsibility. Not every instance of these terms needs to be preceded with the word "your." This is mainly meant for early instances of these terms on the page (i.e. in introductory paragraphs), to establish this idea.
## Inclusivity
Use inclusive language that reflects a diverse readership. Avoid terms that inherently exclude, stereotype, or cause confusion.
### Avoid ableist language
An informal tone can allow for problematic ableist language due to figures of speech and colloquial language. Ableist language includes words like "crazy", "insane", "blind", "dummy", "cripple", and more.
**Examples:**
- Replace _dummy_ with **placeholder, sample**.
- Replace _sanity-check_ with **final check, confirm**.
### Avoid unnecessarily gendered language
Be aware of personal pronouns in examples and outdated gendered terms.
**Best practices:**
- Avoid personal pronouns (i.e., use proper nouns, "the user", etc.).
- If a personal pronoun is needed for clarity or conciseness, default to gender-neutral pronouns (they/them).
**Examples:**
- Replace _man hours_ with one of: **work hours**, **staff hours**, **person hours**.
- Replace _manning_ with **staffing**.
- Replace _man-in-the-middle attack_ with **machine-in-the-middle attack**.
### Write diverse and inclusive examples
Avoid examples that are U.S.-specific or centric.
**Best practices:**
- Avoid U.S.-specific holidays, sports, figures of speech, etc.
- Use a diverse set of names in examples.
### Avoid unnecessarily violent language
Avoid terms that imply violence or harm.
**Examples:**
- Replace "_kill_" with **terminate**.
- Replace "_hit_ Enter" with **press Enter**.
- Replace "_hit_ your resource limits" with **reach your resource limits**
- Replace "_hit_ an error" with **experience an error**.
- Replace "performance _hit_" with **reduced performance**.
- Replace "want to _hit_ up" with **want to visit**.
Terminology around "kill" vs. "stop" vs. "terminate" is nuanced, as described [in this GitHub comment](https://github.com/cockroachlabs/docs/issues/7767#issuecomment-662028864). Use your best judgement.
### Write accessible documentation
- Don't use directional terms as the only clue to location within a page. "Left", "right", "up", "down", "above", and "below" aren't useful for people who use screen-reading software. Good replacements are "preceding" and "following". If you must use a directional term, provide additional text about the location, such as in the Save As dialog box, on the Standard toolbar, or in the title bar.
- Replace "_see_" with **refer to**.
- Provide [alt text](https://en.wikipedia.org/wiki/Alt_attribute) that adequately summarizes the intent of each [image](#images).
- Link text should be the same as or summarize the title of the link target. Avoid **here** and **this documentation**.
### Write about features and users in inclusive ways
Avoid using socially-charged terms for features and technical concepts.
**Examples:**
- Replace _blacklist / whitelist_ with **denylist / allowlist**.
- Replace _master / slave_ with **main/principal/primary/manager** and **secondary/subordinate/worker**.
- Replace _native_ with **core, built-in, top-level, integrated, "built for"** or omit.
- Replace _old_ with **existing, previous, first, original**.
## Capitalization and punctuation
### Capitalization rules
- Use [title case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case) for titles.
- Use [sentence case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case) for all [headings](#headings).
- Capitalize proper nouns, CockroachDB product terms, and the names of UI features.
- **Examples:** CockroachDB, Cockroach Labs, the Overview dashboard, the SQL Queries graph
- Follow [SQL capitalization standards](https://dataschool.com/how-to-teach-people-sql/syntax-conventions/#all-caps-sql-commands) for SQL syntax.
For links to CockroachDB docs, match the capitalization of the linked content:
- Use title case when referring to the linked doc by its page title (for example, `Refer to [Migration Strategy](https://www.cockroachlabs.com/docs/molt/migration-strategy) for more information.`).
- Use sentence case when referring to the linked doc by one of its headers (for example, `Refer to [Capacity planning](https://www.cockroachlabs.com/docs/molt/migration-strategy#capacity-planning) for further guidance.`).
### Punctuation rules
- Use the [Oxford (aka serial) comma](https://en.wikipedia.org/wiki/Serial_comma).
- Use straight `'` rather than curved `‘` quotes.
- Limit semicolon usage. Instead, use two simple sentences.
- **Avoid:** CockroachDB is a distributed database; it scales horizontally across multiple nodes.
**Prefer:** CockroachDB is a distributed database. It scales horizontally across multiple nodes.
- Do not end headings with punctuation (for example, periods or colons).
- Use periods on either all [list items](MarkdownGuide.md#lists) or none. If some items are sentences or complete a sentence, use periods.
- Use colons instead of dashes.
- **Avoid:** **Default** - true
**Prefer:** **Default:** true
- When listing a range of versions, do not use a dash. Instead, separate the first and last versions with `to` (for example, `v22.1.0 to v22.1.4`).
- For singular proper nouns ending in **s**, form the possessive with **'s**.
- **Example:** Postgres's syntax
- For plural words or names ending in **s**, form the possessive with just an apostrophe.
- **Example:** Cockroach Labs' products
- Place commas and periods inside quotation marks (for example, `CockroachDB's availability model is described as "Multi-Active Availability."`). Place other punctuation outside quotation marks (for example, `What is "Multi-Active Availability"?`). When any type of punctuation is part of a quote, place it inside the quotation marks (for example, `To phrase it in the form of a question: "Who are the top 10 users by number of rides on a given date?"`).
- Avoid using slashes "/" and ampersands "&" in place of "or" and "and" respectively, unless space is very limited (such as in a table). Similarly, avoid using "and/or" unless space is very limited. Instead, decide whether "and" or "or" can stand alone, or make use of "both" when the inclusivity must be explicit (for example, `x or y or both`).
## Vale
The CockroachDB documentation uses [Vale](https://vale.sh/) to identify common spelling mistakes or other patterns that may contradict the guidelines in this style guide. Check for items flagged by Vale in the **Files Changed** and **Checks** tabs of the pull request, grouped by file.
Try to address as many of the suggestions as possible. If Vale flags a word that is spelled and used correctly, add the word to `netlify/vale/vocab.txt` in the PR where the word is introduced. For other failed tests, you can work with your reviewer to correct the error in your PR or to improve the Vale test.
## File conventions
File names in the CockroachDB docs repo should be lowercase with a dash between words. File names for docs pages should match the page title whenever possible.
**Examples:**
- `this-is-a-doc.md`
- `name-of-your-image.png`
## Content types
There are four fundamental content types:
- [Concept](#concept)
- [Task](#task)
- [Reference](#reference)
- [Guide](#guide)
### Concept
A _concept_ topic explains how a particular feature works, or how a specific system is designed. Conceptual pages do not provide prescriptive guidance or instruction. For guidance or instruction, refer to [Task](#task) or [Guide](#guide).
- The first sentence answers the implicit question "what is a \?" in the form **A _\_ is ….**.
**Example:** An _index_ is a data structure that improves the speed of data retrieval operations on a database table at the cost of additional writes and storage space to maintain the index data structure.
- Provide as much relevant information as you can, and then link to other pages as necessary. If there is a related [reference](#reference) topic, link to it from within the conceptual topic.
For templates that provide a starting point for writing concept topics, refer to the [concept templates](https://github.com/cockroachlabs/docs/tree/main/templates/concept).
#### Examples
- [Indexes](https://www.cockroachlabs.com/docs/stable/indexes.html)
- [Architecture Overview](https://www.cockroachlabs.com/docs/stable/architecture/overview.html)
- [SQL Layer](https://www.cockroachlabs.com/docs/stable/architecture/sql-layer.html)
### Task
A _task_ topic provides step-by-step instructions to complete a specific goal. Tasks are discrete and action-based. Tasks have the following properties:
- Answers the question "how do I do \?" by describing precisely what to do and the order in which to do it.
- Corresponds to a specific user journey as defined by Product.
- The title or heading should state an actionable goal for the user, ideally of the form **\ [\|\] \ or \**.
**Example:** Create an Index
- The verb ideally should be specific. Avoid generic verbs such as **Use**, **Manage** unless naming a page containing specific tasks.
- Avoid **Your** because you may be using an object that you don't "own".
**Example:** Connect to a Cluster, not Connect to Your Cluster
- Lead with the verb. Don't bury it at the end of the heading.
**Example:** Access DB Console, not DB Console Access.
- Present the steps as a list of numbered headings, e.g., "Step 1. ...".
Tasks should **not** include concept or reference information; instead, a task should link to [Concept](#concept) and [Reference](#reference) topics as needed.
For templates that provide a starting point for writing task topics, refer to the [task templates](https://github.com/cockroachlabs/docs/tree/main/templates/task).
#### Examples
- [Create a CockroachCloud Cluster](https://www.cockroachlabs.com/docs/cockroachcloud/create-your-cluster.html)
- [Upgrade to CockroachDB vXY.Z](https://www.cockroachlabs.com/docs/stable/upgrade-cockroach-version.html)
- [Stream a Changefeed to Snowflake](https://www.cockroachlabs.com/docs/cockroachcloud/stream-changefeed-to-snowflake-aws)
### Reference
_Reference_ topics provide information about a specific CockroachDB function, feature, or interface. Reference topics are detail-oriented, and should include all of the information available on a specific topic, without providing prescriptive guidance. Prescriptive guidance is reserved for [Guide](#guide) topics.
Reference topics typically document programming constructs, interface parameters, or facts about a product, but do not provide explanations of [concepts](#concept) or [tasks](#task).
Reference topics help users understand the precise meaning and effect of CockroachDB SQL language constructs, platforms, configuration options, API parameter values, etc.
- The content should be comprehensive and accurate. This principle might apply to other page types, but it is especially important for reference, as it is the ultimate source of truth for a particular feature or interface.
- The content should be succinct. Details are often presented in table format. Prose is better suited for [Concept](#concept) topics.
For templates that provide a starting point for writing reference topics, refer to the [reference templates](https://github.com/cockroachlabs/docs/tree/main/templates/reference).
#### Examples
- SQL reference: [`CREATE TABLE`](https://www.cockroachlabs.com/docs/stable/create-table.html)
- CLI reference: [`cockroach sql`](https://www.cockroachlabs.com/docs/stable/cockroach-sql.html)
- API reference: [Cluster API](https://www.cockroachlabs.com/docs/api/cluster/v2)
### Guide
_Guides_ offer the reader a perspective on how to decide between a number of different ways of accomplishing a goal. They are meant to provide "guidance" (it's in the name) and should eventually lead the user to perform one or more [Tasks](#task).
To accomplish this goal, guides often link to several different [Concept](#concept) topics and compare and contrast them. They can also link to multiple [Task](#task) topics.
For templates that provide a starting point for writing guide topics, refer to the [guide templates](https://github.com/cockroachlabs/docs/tree/main/templates/guide).
#### Examples
- [Migration Strategy](https://www.cockroachlabs.com/docs/molt/migration-strategy)
- [Disaster Recovery Overview](https://www.cockroachlabs.com/docs/stable/disaster-recovery-overview)
- [Multi-region Survival Goals](https://www.cockroachlabs.com/docs/stable/multiregion-survival-goals)
## Page components
This section describes how to approach page elements other than body text. For Markdown syntax and formatting, refer to the [Markdown Guide](MarkdownGuide.md).
### Code
#### Code blocks
Use separate code blocks for input and output. For example, rather than place both a SQL command and its resulting output within a single code block, place the SQL command inside one code block, followed by its output in another code block.
When you use multiple code blocks to demonstrate a task, interleave the code blocks with text that explains the content of each code block and clarifies where it stands in the overall flow.
**Example:**
```
1. To view all virtual clusters on the standby, run:
{% include_cached copy-clipboard.html %}
~~~ sql
SHOW VIRTUAL CLUSTERS;
~~~
The standby cluster will show the `main` virtual cluster is in a `replicating` state.
~~~
id | name | data_state | service_mode
-----+--------+-------------+---------------
1 | system | ready | shared
3 | main | replicating | none
(2 rows)
~~~
```
#### Placeholders
Code samples often include placeholder values, to be replaced by values specific to a user's environment. To denote that a value in a code sample is a placeholder value that should be replaced, use curly brackets (`{}`).
- **Example:** `SELECT * FROM TABLE {mytable};`.
When you use placeholders, you usually need to define the value within the brackets, if the placeholder value isn't clear. Define placeholder values immediately following the code sample:
- For a single placeholder value, use a follow-up sentence.
- For multiple placeholder values, use a bulleted list.
- For many placeholder values (10+), use a table.
- For large code blocks, define the placeholder values inside the code block with an inline code comment.
Ensure that placeholders are placed within backticks: `SET {session variable}`. This signifies that placeholder values are code.
If the code sample is sensitive to curly bracket characters (as in JavaScript), you can use `<>` instead.
For code block syntax and formatting, refer to the [Markdown Guide](MarkdownGuide.md#code).
### Callouts
CockroachDB docs use three classes of "callouts," which are highlighted blocks of text: tips, notes, and warnings.
- Use a _tip_ to highlight nice-to-know pieces of information.
For example, you might use a tip to link to our GitHub repo's Terraform scripts on the Google Cloud Engine deployment page. It's nice to know it's there, but doesn't clarify anything nor is it critical.
- Use a _note_ to call attention to a piece of clarifying information. This information should **not** be crucial to accomplishing the task in the document.
For example, you might use a note to let users know that the `DELETE` statement only deletes rows and that to delete columns you must use `ALTER TABLE`. This helps clarify `DELETE`'s purpose and point users to the right place.
- Use a _warning_ to express that a piece of information is critical to understand to prevent data loss, security vulnerabilities, or unexpected behavior.
For example, you might include a warning that using `CASCADE` in `DROP INDEX` drops dependent objects without warning. This is critical to prevent users from unexpectedly losing constraints or additional indexes.
**Best practices:**
- Avoid placing callouts next to each other.
- Do not overuse callouts. Most documentation belongs in the body of a page rather than in a callout.
For code block syntax and formatting, refer to the [Markdown Guide](MarkdownGuide.md#callouts).
### Images
Use images to clarify a topic, but only use them as needed. Images are either:
- **Screenshots:** Depict a UI element. Screenshots should only show enough of the UI that the user can easily orient themselves and understand what they are being shown. Exclude UI elements that are not relevant to the screenshot's purpose. If a screenshot needs an annotation, use a red box.
**Note:** Screenshots are difficult to keep current, and impact accessibility. Use a screenshot only if it is necessary for the user to accomplish a task or understand a feature. For example, in a page on troubleshooting cluster performance, a screenshot of a Contention metric graph in the DB Console might be used to depict a cluster with high contention. The same screenshot would not be necessary in a reference topic about the DB Console user interface.
To optimize accessibility and SEO, a screenshot should be accompanied by text and [alt-text](#write-accessible-documentation) describing its contents.
- **Diagrams:** Visualize a complicated mechanism. Diagrams should not reproduce such complexity, and can simplify a process. A diagram should be easy to follow.
The Docs team uses the following tools to compose diagrams:
- [Monodraw](https://monodraw.helftone.com/): useful for abstract concept diagrams
- [Omnigraffle](https://www.omnigroup.com/omnigraffle): useful for diagrams with branded elements like logos and colors
Icons for diagrams can be sourced from the [`cockroach-studios`](https://github.com/cockroachlabs/cockroach-studios/tree/main/icons) repo. The `.gstencil` file in the `icons` directory is an Omnigraffle template listing our branded primary/secondary/extended color palette.
For image syntax and embedding, refer to the [Markdown Guide](MarkdownGuide.md#images).
### Videos
Like images, use videos to clarify a topic, but only use them as needed. Typically, videos should be hosted on the official [CockroachDB YouTube page](https://www.youtube.com/@cockroachdb) and are surfaced by our Marketing team.
Place videos under their own page heading. For video embedding syntax, refer to the [Markdown Guide](MarkdownGuide.md#videos).
### Include files
Sometimes content needs to be duplicated across **two or more pages** in the documentation. For example, there may be several pages that need the same cluster setup, but describe how to use different features. Or a [callout](#callout) needs to be added to several different pages.
In these situations, use an [_include file_](https://jekyllrb.com/docs/includes/). An include file is a separate Markdown file (stored in `_includes/some/shared-file.md`) whose content is shared across multiple pages.
**Note:** Using include files adds complexity to the docs site architecture and build process. Consider linking to an existing page or subheading rather than using an include file.
For include file syntax, refer to the [Markdown Guide](MarkdownGuide.md#include-files).
### Links
#### GitHub links
[Release notes](https://www.cockroachlabs.com/docs/releases/index.html), [technical advisories](https://www.cockroachlabs.com/docs/advisories/index.html), and [known limitations](https://www.cockroachlabs.com/docs/stable/known-limitations.html) contain links to individual GitHub issues and pull requests.
Reference issues and pull requests by their corresponding number, prepended with `#`.
**Example:** `[#1](https://github.com/cockroachlabs/docs/pull/1)`
#### External links
When linking to third-party documentation, consider the purpose and maintenance implications. Link to third-party sources for integration workflows, official API references, and tool configurations that change frequently.
**Best practices:**
- Link to stable, official documentation pages when possible and ensure links point to the appropriate version of the external product.
- Avoid linking to blog posts or unofficial sources.
- Consider whether a brief explanation in our docs would be more reliable than an external link.
For link syntax, refer to the [Markdown Guide](MarkdownGuide.md#links).
## Page sections
For page headings, refer to the [Markdown Guide](MarkdownGuide.md#page-headings).
### Before you begin
A `Before you begin` section describes prerequisites for following the page content. These may be setup requirements or contextual information that's helpful to the task. Place this section immediately after the page introduction.
**Best practices:**
- Keep prerequisites specific and actionable.
- Link to relevant setup or configuration pages.
- Use a bulleted list for multiple prerequisites.
- Avoid generic statements like "Have CockroachDB installed" unless the page specifically requires a fresh installation.
### Known limitations
A `Known limitations` section describes unexpected database behaviors that differ from SQL standards, PostgreSQL behavior, or expected functionality. Document all known limitations on the [Known Limitations](https://www.cockroachlabs.com/docs/stable/known-limitations.html) page and on feature-specific pages under a dedicated "Known limitations" header.
Document limitations during GA release weeks or when discovered post-release. For detailed procedures, refer to the [documentation wiki](https://cockroachlabs.atlassian.net/wiki/spaces/ED/pages/3516825623/Document+known+limitations).
### See also
A `See also` section contains links to related pages. This is always the last section in a page.
---
## File: src/api/_config_base.yml
baseurl: /docs/api
defaults:
-
scope:
path: "" # an empty string here means all files in the project
values:
layout: "tutorial"
destination: _site/docs/api
exclude:
- __tests__
- build
- scripts
- vendor
- archived
- package.json
- package-lock.json
- build-netlify.sh
include:
- _redirects
jekyll-minifier:
compress_css: 'false'
compress_javascript: 'true'
compress_js_templates: 'false'
compress_json: 'true'
exclude:
- '**.html'
- js/rapidoc-min.js
preserve_line_breaks: 'false'
preserve_php: 'true'
remove_comments: 'true'
remove_form_attributes: 'false'
remove_http_protocol: 'false'
remove_https_protocol: 'false'
remove_input_attributes: 'false'
remove_intertag_spaces: 'false'
remove_javascript_protocol: 'false'
remove_link_attributes: 'false'
remove_multi_spaces: 'false'
remove_quotes: 'false'
remove_script_attributes: 'false'
remove_spaces_inside_tags: 'false'
remove_style_attributes: 'false'
simple_boolean_attributes: 'false'
simple_doctype: 'false'
uglifier_args:
harmony: 'true'
jekyll_get_json:
- data: cloud_api_releases
json: https://cockroachlabs.cloud/assets/docs/api/manifest.json
main_url: https://www.cockroachlabs.com
plugins:
- jekyll-include-cache
- jekyll-last-modified-at
- jekyll-minifier
- jekyll-get-json
site_title: CockroachDB Docs
---
## File: src/api/package.json
{
"name": "cockroachdb-docs",
"version": "2.0.0",
"devDependencies": {
"@netlify/plugin-lighthouse": "^4.0.7",
"jest": "^26",
"jest-cli": "^26"
},
"dependencies": {
"front-matter": "^4.0.2",
"redoc-cli": "^0.11.4",
"snippet-enricher-cli": "^0.0.8",
"swagger2openapi": "^7.0.5",
"yaml": "^1.10.2"
}
}
---
## File: src/api/.htmltest.yml
DirectoryPath: "_site"
ExternalTimeout: 30
IgnoreDirs:
- ^docs/stable
- ^docs/dev
- ^docs/v1.0
- ^docs/v1.1
- ^docs/v1.2
- ^docs/v2.0
- ^docs/v2.1
- ^docs/v19.1
- ^docs/v19.2
- ^docs/v20.1
- ^docs/v20.2
- ^docs/v21.1
IgnoreURLs:
- "http://localhost:*"
- "http://roach-single/*"
- "https://roach-single/*"
- "https://github.com/*"
- "https://raw.github.com/*"
- "https://docs.github.com/*"
- "https://movr.cloud"
- "https://support.cockroachlabs.com/*"
- "https://www.cockroachlabs.com/*"
- "https://www.php.net/*"
- "https://crates.io/*"
- "https://docs.pipenv.org/*"
- "https://arxiv.org/*"
- "https://fonts.googleapis.com/*"
- "https://fonts.gstatic.com/*"
- "https://typeorm.io/*"
- "https://www.googleadservices.com/*"
IgnoreInternalEmptyHash: true
TestFilesConcurrently: true
DocumentConcurrencyLimit: 16
---
## File: src/api/cloud/v1.md
---
title: CockroachDB Cloud API
summary: Learn about the CockroachDB Cloud API
layout: api
docs_area: reference.api
---
{% assign releases = site.data.cloud_api_releases.specs %}
**nav-logo** slot
Version:
---
## File: src/api/cluster/v2.md
---
title: CockroachDB v2 API
summary: Learn about the CockroachDB v2 API (2.0.0).
layout: api
docs_area: reference.api
---
# Configuration
ALGOLIA_INDEX_ENVIRONMENT=staging # or 'production'
ALGOLIA_STATE_DIR=/opt/teamcity-data/algolia_state
ALGOLIA_FORCE_FULL=false # Set to 'true' to force full reindex
```
### Server Setup
```bash
# On TeamCity agent machine
sudo mkdir -p /opt/teamcity-data/algolia_state
sudo chown teamcity:teamcity /opt/teamcity-data/algolia_state
sudo chmod 755 /opt/teamcity-data/algolia_state
```
## 🎯 Smart Indexing Logic
### Automatic Full vs Incremental Decision
The wrapper automatically decides between full and incremental indexing:
**Full Indexing Triggers:**
1. **First Run**: No state file exists
2. **Force Override**: `ALGOLIA_FORCE_FULL=true`
3. **Corrupted State**: Invalid state file
4. **Stale State**: State file >7 days old
5. **Content Changes**: Git commits affecting source files
6. **Config Changes**: `_config_cockroachdb.yml` modified
7. **Incomplete Previous**: <100 files tracked (indicates failure)
**Incremental Indexing (Default):**
- Recent valid state file
- No source file changes
- No configuration changes
- Previous indexing was complete
### Version Detection
Dynamically reads from `_config_cockroachdb.yml`:
```yaml
versions:
stable: v25.3 # ← Automatically detected and used
dev: v25.3
```
**Indexing Rules:**
- ✅ Always include: `/releases/`, `/cockroachcloud/`, `/advisories/`, `/molt/`
- ✅ Include stable version files: Files containing `v25.3`
- ❌ Exclude old versions: `v24.x`, `v23.x`, etc.
- 🔄 Smart dev handling: Only exclude dev if stable equivalent exists
## 🧠 Intelligent Bloat Removal
### What Gets Removed
- **85K+ Duplicate Records**: Content deduplication using MD5 hashing
- **UI Spam**: Navigation elements, dropdowns, version selectors
- **Table Bloat**: Repetitive headers, "Yes/No" cells
- **Download Spam**: "SQL shell Binary", "Full Binary" repetition
- **Grammar Noise**: "referenced by:", "no references"
- **Version Clutter**: Standalone version numbers, dates
### What Gets Preserved
- ✅ All SQL commands and syntax
- ✅ Technical documentation content
- ✅ Error messages and troubleshooting
- ✅ Release notes and changelogs
- ✅ Important short technical terms
- ✅ Complete page coverage (no artificial limits)
## 📊 Performance Metrics
### Size Optimization
```
Production Index: 157,471 records
Naive Indexing: ~350,000 records
Size Reduction: 55% smaller
Quality: Maintained/Improved
```
### Speed Improvements
```
Jekyll Gem Full Rebuild: ~15-20 minutes
Python Incremental: ~2-3 minutes
Python Full Rebuild: ~8-10 minutes
```
## 🧪 Testing & Validation
### Comprehensive Test Coverage
Run the full test suite:
```bash
# Test wrapper decision logic (10 scenarios)
python3 test_wrapper_scenarios.py
# Test incremental indexing functionality
python3 test_incremental_indexing.py
# Verify production parity
python3 check_ranking_parity.py
# Test all file processing
python3 test_all_files.py
```
### Test Scenarios
1. ✅ **First Run Detection** - Missing state file → Full indexing
2. ✅ **Force Full Override** - `ALGOLIA_FORCE_FULL=true` → Full indexing
3. ✅ **Corrupted State Handling** - Invalid JSON → Full indexing
4. ✅ **Stale State Detection** - >7 days old → Full indexing
5. ✅ **Git Change Detection** - Source commits → Full indexing
6. ✅ **Config Change Detection** - `_config*.yml` changes → Full indexing
7. ✅ **Incomplete Recovery** - <100 files tracked → Full indexing
8. ✅ **Normal Incremental** - Healthy state → Incremental indexing
9. ✅ **Error Recovery** - Graceful handling of all failure modes
10. ✅ **State Persistence** - File tracking across runs
## 🔧 Configuration Options
### Environment Variables
```bash
# Core Configuration
ALGOLIA_APP_ID="7RXZLDVR5F" # Algolia application ID
ALGOLIA_ADMIN_API_KEY="" # Admin API key (secure)
ALGOLIA_INDEX_NAME="staging_cockroach_docs" # Target index name
# Smart Wrapper Configuration
ALGOLIA_INDEX_ENVIRONMENT="staging" # Environment (staging/production)
ALGOLIA_STATE_DIR="/opt/teamcity-data/algolia_state" # Persistent state directory
ALGOLIA_FORCE_FULL="false" # Force full reindex override
# Indexer Configuration
ALGOLIA_INCREMENTAL="false" # Set by wrapper automatically
ALGOLIA_TRACK_FILE="/path/to/state.json" # Set by wrapper automatically
SITE_DIR="_site" # Jekyll build output directory
```
## 📈 Monitoring & Logging
### Comprehensive Logging
The system provides detailed logging for monitoring:
```json
{
"timestamp": "2025-09-09T16:20:00Z",
"environment": "staging",
"index_name": "staging_cockroach_docs",
"mode": "INCREMENTAL",
"reason": "State file exists and is recent",
"success": true,
"duration_seconds": 142.5,
"state_file_exists": true,
"state_file_size": 125430
}
```
### Log Locations
```bash
# Wrapper execution logs
/opt/teamcity-data/algolia_state/indexing_log_.json
# State tracking file
/opt/teamcity-data/algolia_state/files_tracked_.json
# TeamCity build logs (stdout/stderr)
```
## 🚨 Troubleshooting
### Common Issues
**❌ "State file not found"**
- **Cause**: First run or state file was deleted
- **Solution**: Normal - will do full indexing automatically
**❌ "Git commits detected"**
- **Cause**: Source files changed since last indexing
- **Solution**: Normal - will do full indexing automatically
**❌ "Missing ALGOLIA_ADMIN_API_KEY"**
- **Cause**: Environment variable not set in TeamCity
- **Solution**: Add secure variable in TeamCity configuration
**❌ "Too few files tracked"**
- **Cause**: Previous indexing was incomplete
- **Solution**: Normal - will do full indexing to recover
**❌ "Indexer script not found"**
- **Cause**: Missing `algolia_index_intelligent_bloat_removal.py`
- **Solution**: Ensure all files are deployed with the wrapper
### Manual Override
Force a full reindex:
```bash
# In TeamCity, set parameter:
ALGOLIA_FORCE_FULL=true
```
### State File Management
```bash
# View current state
cat /opt/teamcity-data/algolia_state/files_tracked_staging.json
# Reset state (forces full reindex next run)
rm /opt/teamcity-data/algolia_state/files_tracked_staging.json
# View recent run logs
cat /opt/teamcity-data/algolia_state/indexing_log_staging.json
```
## 🔄 Migration Process
### Phase 1: Validation (Complete)
- ✅ Built and tested Python indexing system
- ✅ Validated against production index (96%+ parity)
- ✅ Comprehensive test coverage (100% pass rate)
- ✅ Performance optimization and bloat removal
### Phase 2: Staging Deployment (Next)
- Deploy to TeamCity staging environment
- Configure environment variables and state persistence
- Monitor performance and validate incremental updates
- Compare search quality against production
### Phase 3: Production Deployment
- Deploy to production TeamCity environment
- Switch from Jekyll Algolia gem to Python system
- Monitor production search quality and performance
- Remove Jekyll Algolia gem dependency
## 💡 Key Innovations
### 1. **Intelligent Bloat Detection**
Instead of naive content extraction, the system uses pattern recognition to identify and remove repetitive, low-value content while preserving technical documentation.
### 2. **Stable Object IDs**
Object IDs are based on URL + position, not content. This enables true incremental updates - only records with structural changes get new IDs.
### 3. **Smart Decision Logic**
The wrapper uses multiple signals (git history, file timestamps, state analysis) to automatically choose the optimal indexing strategy.
### 4. **Production Parity**
Field mapping, content extraction, and ranking factors match the existing production index exactly.
### 5. **Zero-Downtime Deployment**
Incremental indexing allows continuous updates without search interruption.
## 📞 Support
For questions or issues:
1. **Development**: Check test failures and logs
2. **Staging Issues**: Review TeamCity build logs and state files
3. **Production Issues**: Check monitoring logs and consider manual override
4. **Search Quality**: Run parity testing scripts for analysis
## 🎯 Success Metrics
- ✅ **100%** test pass rate
- ✅ **96%+** production parity
- ✅ **55%** index size reduction
- ✅ **3x** faster incremental updates
- ✅ **Zero** git commits from state management
- ✅ **Full** TeamCity integration ready
---
## File: src/current/.htmltest.yml
DirectoryPath: "_site"
ExternalTimeout: 30
IgnoreDirs:
- ^docs/stable
- ^docs/dev
- ^docs/v1.0
- ^docs/v1.1
- ^docs/v1.2
- ^docs/v2.0
- ^docs/v2.1
- ^docs/v19.1
- ^docs/v19.2
- ^docs/v20.1
- ^docs/v20.2
- ^docs/v21.1
IgnoreURLs:
- "http://localhost:*"
- "http://roach-single/*"
- "https://roach-single/*"
- "https://github.com/*"
- "https://raw.github.com/*"
- "https://docs.github.com/*"
- "https://movr.cloud"
- "https://support.cockroachlabs.com/*"
- "https://www.php.net/*"
- "https://crates.io/*"
- "https://docs.pipenv.org/*"
- "https://arxiv.org/*"
- "https://fonts.googleapis.com/*"
- "https://fonts.gstatic.com/*"
- "https://typeorm.io/*"
- "https://www.googleadservices.com/*"
IgnoreInternalEmptyHash: true
TestFilesConcurrently: true
DocumentConcurrencyLimit: 16
---
## File: src/current/_data/alerts.yml
tip: ' **Tip: **'
note: ' **Note: **'
important: ' **Important: **'
warning: ' **Warning: **'
version: ''
end: ''
callout_danger: 'Warning:'
callout_success: 'Tip:'
callout_info: 'Note:'
callout_version: ''
hr_faded: '
'
hr_shaded: '
'
---
## File: src/current/_data/cards.yml
develop:
- link: "/cockroachcloud/quickstart.html"
title: "Create a new cluster"
text: "Create and connect to a new CockroachDB cluster."
- link: "/PREFIX/install-client-drivers.html"
title: "Install drivers"
text: "Install client drivers for your application."
- link: "/PREFIX/connect-to-the-database.html"
title: "Connect to a cluster"
text: "Get details on how to connect to a CockroachDB cluster using your favorite language and framework."
- link: "/PREFIX/developer-basics.html"
title: "Developer basics"
text: "A quick overview of key concepts developers need to know about CockroachDB."
text: "Submit SQL queries to retrieve data from your cluster."
- link: "/PREFIX/schema-design-overview.html"
title: "Design a schema"
text: "Details and best practices about designing schemas for your data."
- link: "/PREFIX/insert.html"
title: "Write data"
text: "How to insert data into your cluster."
- link: "/PREFIX/query-behavior-troubleshooting.html"
title: "Troubleshoot your application"
text: "Handle errors and solve problems with your application."
- link: '/PREFIX/make-queries-fast.html'
title: "Optimize performance"
text: "How to make your queries run as fast as possible."
---
## File: src/current/_data/constants.yml
cockroach_range_lease_duration: 6s
cockroach_range_lease_acquisition_timeout: 4s
cockroach_network_timeout: 2s
cockroach_network_connection_timeout: 4s
cockroach_network_client_ping_interval: 1s
cockroach_network_client_ping_timeout: 6s
cockroach_raft_election_timeout_ticks: 4
cockroach_raft_reproposal_timeout_ticks: 6
cockroach_raft_tick_interval: 500ms
---
## File: src/current/_data/menus.yml
# ---
# serverless:
# - identifier: product
# name: Product
# url: https://www.cockroachlabs.com/product/
# weight: 100
# params:
# image: /images/menu-product.png
# text: A distributed SQL datatabase designed for speed, scale,and survival
# product_caps:
# # Left
# - identifier: product-capabilities
# name: Elastic Scale
# url: https://www.cockroachlabs.com/product/scale/
# weight: 100
# - name: Cloud-Native & Kubernetes
# url: https://www.cockroachlabs.com/product/kubernetes/
# - name: Built-in Survivability
# url: https://www.cockroachlabs.com/product/resilience/
# # Right
# - name: Familiar, Consistent SQL
# url: https://www.cockroachlabs.com/product/sql/
# - name: Global Data
# url: https://www.cockroachlabs.com/product/geo-partitioning/
# solutions:
# - identifier: solutions
# name: Solutions
# url: https://www.cockroachlabs.com/solutions/
# weight: 110
# params:
# # image: /img/menu-product.png
# text: See how our customers use CockroachDB to handle their critical workloads.
# solutions_industries:
# - name: Finance
# url: https://www.cockroachlabs.com/solutions/verticals/financialservices/
# weight: 100
# - name: Gaming
# url: https://www.cockroachlabs.com/solutions/verticals/gaming/
# weight: 100
# - name: Manufacturing & Logistics
# url: https://resources.cockroachlabs.com/manufacturing-logistics
# weight: 100
# - name: Media & Streaming
# url: https://www.cockroachlabs.com/solutions/verticals/media/
# - name: Real-Money Gaming
# url: https://www.cockroachlabs.com/solutions/verticals/gambling/
# weight: 100
# - name: Retail & eCommerce
# url: https://www.cockroachlabs.com/solutions/verticals/retail-ecommerce/
# weight: 100
# - name: SaaS
# url: https://www.cockroachlabs.com/solutions/verticals/saas
# weight: 100
# - name: Startups
# url: https://resources.cockroachlabs.com/startups
# weight: 100
# solutions_usecase:
# - name: Cloud-Native & Kubernetes
# url: https://resources.cockroachlabs.com/cloud-native-kubernetes
# weight: 600
# - name: Scale & Resilience
# url: https://resources.cockroachlabs.com/scale-resilience
# weight: 700
# - name: Data Privacy & Security
# url: https://resources.cockroachlabs.com/privacy-compliance
# weight: 800
# - name: Distributed Apps
# url: https://resources.cockroachlabs.com/distributed-apps
# weight: 900
# resources:
# - identifier: resources
# name: Resources
# url: https://www.cockroachlabs.com/resources/
# weight: 120
# params:
# # image: /img/menu-product.png
# text: "Cockroach University
World-class training and tutorials for beginners and advanced use cases."
# resources_learn:
# - name: Resource center
# url: https://www.cockroachlabs.com/resources/
# weight: 100
# - name: Blog
# url: https://www.cockroachlabs.com/blog/
# weight: 200
# - name: Developers
# url: https://www.cockroachlabs.com/developers/
# weight: 200
# - name: Webinars
# url: https://www.cockroachlabs.com/community/webinars/
# weight: 200
# - name: Podcast
# url: https://www.cockroachlabs.com/big-ideas-podcast/
# weight: 200
# resources_support:
# - name: Slack
# url: https://www.cockroachlabs.com/join-community/
# - name: Support Portal
# url: https://support.cockroachlabs.com/hc/en-us?__hstc=181257784.2bc4222d759d3d555572287e7b610f03.1579111962927.1604502276741.1604544514798.361&__hssc=181257784.63.1604544514798&__hsfp=407609322
# docs:
# - identifier: docs
# name: Docs Hub
# url: https://www.cockroachlabs.com/docs/
# weight: 120
# params:
# # image: /img/menu-product.png
# text: "Docs Hub
Access tutorials, guides, example applications, and much more."
# docs_items:
# - name: Quickstart
# url: https://www.cockroachlabs.com/docs/cockroachcloud/quickstart.html
# weight: 100
# - name: FAQ
# url: https://www.cockroachlabs.com/docs/stable/frequently-asked-questions.html
# weight: 200
# - name: Example applications
# url: https://www.cockroachlabs.com/docs/stable/example-apps.html
# weight: 300
# - name: Architecture Overview
# url: https://www.cockroachlabs.com/docs/stable/architecture/overview.html
# weight: 400
# company:
# - identifier: company
# name: Company
# url: https://www.cockroachlabs.com/company/
# weight: 110
# params:
# # image: /img/menu-product.png
# text: CockroachDB is trusted by innovators around the world, big and small. Take a look at how they use CockroachDB to build future-proofed applications.
# company_items:
# - name: Company News & Culture
# url: https://www.cockroachlabs.com/blog/culture/
# - name: Our Story
# url: https://www.cockroachlabs.com/about/
# - name: Partners
# url: https://www.cockroachlabs.com/partners/
# - name: Work at Cockroach Labs
# url: https://www.cockroachlabs.com/careers/
# # End New Serverless Nav
# main_right:
# - identifier: contact
# pre: ""
# name: Contact Us
# url: https://www.cockroachlabs.com/contact/
# weight: 100
# - identifier: sign_in
# pre: ""
# name: Sign In
# url: https://cockroachlabs.cloud/
# weight: 110
# - identifier: get_started
# pre: ""
# name: Get CockroachDB
# url: https://www.cockroachlabs.com/get-started-cockroachdb/
# weight: 120
# blog_sub:
# - identifier: blog
# pre: ""
# name: Blog
# url: https://www.cockroachlabs.com/blog/
# weight: -100
# - identifier: culture
# pre: ""
# name: Company + Culture
# url: https://www.cockroachlabs.com/blog/culture/
# weight: -100
# - identifier: engineering
# pre: ""
# name: Engineering
# url: https://www.cockroachlabs.com/blog/engineering/
# weight: -100
# - identifier: product
# pre: ""
# name: Product
# url: https://www.cockroachlabs.com/blog/product/
# weight: -100
# - identifier: customer-stories
# pre: ""
# name: Customer Stories
# url: https://www.cockroachlabs.com/blog/customer-stories/
# weight: -100
# careers_sub:
# - identifier: careers
# pre: ""
# name: Careers
# url: https://www.cockroachlabs.com/careers/
# weight: -100
# - identifier: open-positions
# pre: ""
# name: Open Positions
# url: https://www.cockroachlabs.com/careers/open-positions/
# weight: -100
# - identifier: meet-the-team
# pre: ""
# name: Meet The Team
# url: https://www.cockroachlabs.com/careers/meet-the-team/
# weight: -100
# solutions_sub:
# - identifier: solutions
# pre: ""
# name: Solutions
# url: https://www.cockroachlabs.com/solutions/
# weight: -200
# - identifier: initiatives
# pre: ""
# name: Initiatives
# url: https://www.cockroachlabs.com/solutions/initiatives/
# weight: -100
# - identifier: use-cases
# pre: ""
# name: Use Cases
# url: https://www.cockroachlabs.com/solutions/use-cases/
# weight: -100
# - identifier: verticals
# pre: ""
# name: Verticals
# url: https://www.cockroachlabs.com/solutions/Verticals/
# weight: -100
---
## File: src/current/_data/menuwhy.yml
- identifier: familiar_sql
pre: "Build fast & build to last"
name: Familiar SQL
url: /product/sql/
weight: 100
- identifier: elastic_sql
pre: "Elastic Scale"
name: Grow locally and/or globally
url: /product/scale/
weight: 110
---
## File: src/current/_data/products.yml
serverless: Serverless
dedicated: Dedicated
dedicated-advanced: Dedicated advanced
core: self-hosted
enterprise: Enterprise
cloud: Cloud
basic: Basic
standard: Standard
advanced: Advanced
public-operator: Public operator
cockroachdb-operator: CockroachDB operator
---
## File: src/current/_data/redirects.yml
############################################################
# How to use this file:
#
# Add a new block like this in alphabetical order based on its category:
#
#
# Here’s the sample syntax of the file:
#
# - destination: new-file-name-with-md-extension.md#optional-anchor
# sources:
# - old-file-name-with-md-extension.md
# - other-old-file-name.md
# temporary: true|false # (optional, default = false
# force: true|false # optional, default = false
# versions: ['v22.1', 'v22.2'] # optional
#
# - destination is the final page where each source should land.
# Each destination must have the .md file extension.
# - sources is an array of pages you wish to route to the
# destination page. Even if you only have one source, it must use
# YML’s array syntax (full spec here: https://yaml.org/).
# Each source must have the .md extension.
# - temporary is an optional boolean field that dictates whether
# you return a 301 (false, default) or a 302 (true).
# - force is an optional boolean field that dictates whether a
# force redirect should occur. This is equivalent to adding an
# exclamation point (!) to the end of the status code. docs:
# https://docs.netlify.com/routing/redirects/redirect-options/#force-redirects
# - versions is an optional array of strings containing the
# versions to which a redirect should apply. If there is an item
# in the list of versions that matches a major version in
# versions.csv, Jekyll will automatically add a redirect
# for the dev and stable aliases for that page. versions.csv:
# https://github.com/cockroachlabs/docs/blob/main/src/current/_data/versions.csv
#
# Each redirect added in redirects.yml generates a redirect
# for the page without the .md extension and a redirect for
# the page with the .md extension. This helps with making
# sure inlinks to our docs don’t 404, which hurts our SEO.
#
# If using versions, redirects will generate as follows:
#
# # for each version in versions:
# // //
# // //
# # if a version exists in versions.csv:
# /dev/ /dev/
# /dev/ /dev/
# /stable/ /stable/
# /stable/ /stable/
#
# Our is /docs.
#
# If not using versions, this is how redirects will generate:
#
# / /
# / /
#
# No dev or stable redirects are added automatically if not using
# the versions field. Note that you must manually specify the full
# path after .
#
# Using :version as a placeholder includes any string of text between
# the forward slashes, including dev, stable, v21.2, and gobbledygook.
# You can also name your placeholder anything you like, including
# :gobbledygook.
#
# versions, sources, and destination all support the use of
# placeholders. Docs here:
# https://docs.netlify.com/routing/redirects/redirect-options/#placeholders
#
# sources and destination support splats (* in the source,
# :splat in the destination). Docs here:
# https://docs.netlify.com/routing/redirects/redirect-options/#splats
############################################################
- destination: advisories/index.md
sources: ['advisories/advisories.md']
# Renamed pages
- destination: admin-ui-overview.md
sources: ['explore-the-admin-ui.md']
versions: ['v1.1', 'v2.0', 'v2.1', 'v19.1', 'v20.1']
- destination: architecture/distribution-layer.md#range-merges
sources: ['range-merges.md']
versions: ['v21.1']
- destination: architecture/overview.md
sources: ['architecture/index.md']
versions: ['v1.1', 'v2.0', 'v2.1', 'v19.1', 'v20.1', 'v20.2', 'v21.1']
- destination: authorization.md
sources: ['create-and-manage-users.md']
versions: ['v20.1', 'v20.2', 'v21.1']
- destination: authorization.md
sources: ['roles.md']
versions: ['v20.1', 'v20.2', 'v21.1']
- destination: backup-and-restore.md
sources:
- backup-data.md
- restore-data.md
versions: ['v2.1', 'v19.1', 'v20.1']
- destination: cdc-queries.md
sources: ['cdc-transformations.md']
versions: ['v23.1']
- destination: change-data-capture-overview.md
sources: ['change-data-capture.md']
versions: ['v21.2']
- destination: cloud-org-sso.md
sources: ['cloud-sso.md']
versions: ['cockroachcloud']
- destination: cockroach-cert.md
sources: ['create-security-certificates.md']
versions: ['v20.1', 'v20.2', 'v21.1']
- destination: cockroach-debug-ballast.md
sources: ['debug-ballast.md']
versions: ['v20.1', 'v20.2', 'v21.1']
- destination: cockroach-debug-encryption-active-key.md
sources: ['debug-encryption-active-key.md']
versions: ['v20.1', 'v20.2', 'v21.1']
- destination: cockroach-debug-merge-logs.md
sources: ['debug-merge-logs.md']
versions: ['v20.1', 'v20.2', 'v21.1']
- destination: cockroach-debug-zip.md
sources: ['debug-zip.md']
versions: ['v20.1', 'v20.2', 'v21.1']
- destination: cockroach-dump.md
sources: ['sql-dump.md']
versions: ['v20.1', 'v20.2', 'v21.1']
- destination: cockroach-gen.md
sources: ['generate-cockroachdb-resources.md']
versions: ['v20.1', 'v20.2', 'v21.1']
- destination: cockroach-init.md
sources: ['initialize-a-cluster.md']
versions: ['v20.1', 'v20.2', 'v21.1']
- destination: cockroach-node.md
sources: ['view-node-details.md']
versions: ['v20.1', 'v20.2', 'v21.1']
- destination: cockroach-quit.md
sources: ['stop-a-node.md']
versions: ['v20.1', 'v20.2', 'v21.1']
- destination: cockroach-sql.md
sources: ['use-the-built-in-sql-client.md']
versions: ['v20.1', 'v20.2', 'v21.1', 'v21.2', 'v21.2', 'v22.2', 'v23.1', 'v23.2']
- destination: cockroach-sqlfmt.md
sources: ['use-the-query-formatter.md']
versions: ['v20.1', 'v20.2', 'v21.1']
- destination: cockroach-start.md
sources: ['start-a-node.md']
versions: ['v20.1', 'v20.2', 'v21.1']
- destination: cockroach-version.md
sources: ['view-version-details.md']
versions: ['v20.1', 'v20.2', 'v21.1']
- destination: cockroachdb-feature-availability.md
sources:
- experimental-features.md
- features-in-preview.md
versions: ['v22.1', 'v22.2', 'v23.1']
- destination: common-errors.md
sources: ['general-troubleshooting.md']
versions: [':version']
- destination: connect-to-a-serverless-cluster.md
sources: ['connect-to-a-free-cluster.md']
versions: ['cockroachcloud']
- destination: copy.md
sources: ['copy-from.md']
versions: ['v23.1', 'v23.2', 'v24.1', 'v24.2', 'v24.3', 'v25.1']
- destination: cost-based-optimizer.md
sources: ['sql-optimizer.md']
versions: [':version']
- destination: create-a-serverless-cluster.md
sources: ['create-a-free-cluster.md']
versions: ['cockroachcloud']
- destination: demo-cockroachdb-resilience.md
sources: ['demo-fault-tolerance-and-recovery.md']
versions: ['v24.2', 'v24.3']
- destination: demo-low-latency-multi-region-deployment.md
sources: ['demo-geo-partitioning.md']
versions: ['v20.1', 'v20.2', 'v21.1']
- destination: demo-replication-and-rebalancing.md
sources:
- demo-automatic-rebalancing.md
- demo-data-replication.md
versions: ['v20.1', 'v20.2', 'v21.1']
- destination: v23.2/disaster-recovery-planning.md
sources: ['v23.2/disaster-recovery.md']
- destination: dev/disaster-recovery-planning.md
sources: ['dev/disaster-recovery.md']
- destination: example-apps.md
sources: ['build-an-app-with-cockroachdb.md']
versions: ['v21.2']
- destination: example-apps.md
sources: ['tutorials-overview.md']
versions: ['v23.1']
- destination: example-apps.md#python
sources: ['build-a-python-app-with-cockroachdb-pony.md']
versions: ['v20.2', 'v21.1', 'v21.2', 'v22.1', 'v22.2', 'v23.1']
- destination: dev/failover-replication.md
sources: ['cutover-replication.md']
versions: ['24.3', '24.1']
- destination: failover-replication.md
sources: ['cutover-replication.md']
versions: ['24.3', '24.1']
- destination: fips.md
sources: ['fips-compliance.md']
versions: ['v23.1']
- destination: global-tables.md
sources: ['topology-duplicate-indexes.md']
versions: ['v21.1', 'v21.2', 'v22.1', 'v22.2', 'v23.1']
- destination: grant.md
sources: ['grant-roles.md']
versions: ['v21.1']
- destination: how-does-a-changefeed-work.md
sources: ['how-does-an-enterprise-changefeed-work.md']
versions: ['v25.2', 'v25.1', 'v24.3']
- destination: kubernetes-overview.md
sources: ['operate-cockroachdb-kubernetes.md']
versions: ['v21.2']
- destination: log-sql-activity-to-datadog.md
sources: ['log-sql-statistics-to-datadog.md']
versions: ['v23.1', 'v23.2', 'v24.1', 'v24.2', 'v24.3', 'v25.1']
- destination: logging-overview.md
sources: ['debug-and-error-logs.md']
versions: ['v21.1']
- destination: managing-access.md
sources:
- console-access-management.md
- user-authorization.md
versions: ['cockroachcloud']
- destination: manual-deployment.md
sources: ['cloud-deployment.md']
versions: ['v1.1', 'v2.0', 'v2.1', 'v19.1', 'v20.1', 'v20.2', 'v21.1']
- destination: plan-your-cluster-serverless.md
sources:
- 'planning-your-serverless-cluster.md'
- 'learn-about-pricing.md'
- 'learn-about-request-units.md'
versions: ['cockroachcloud']
- destination: provision-a-cluster-with-terraform.md
sources:
- 'migrate-from-free-to-dedicated.md'
- 'migrate-from-serverless-to-dedicated.md'
versions: ['cockroachcloud']
- destination: molt/migrate-data-load-and-replication.md?filters=oracle
sources: [':version/migrate-from-oracle.md']
- destination: molt/migrate-data-load-and-replication.md?filters=mysql
sources: [':version/migrate-from-mysql.md']
- destination: molt/migrate-data-load-and-replication.md
sources: [':version/migrate-from-postgres.md']
- destination: molt/migrate-load-replicate.md
sources: ['molt/migrate-data-load-replicate-only.md']
- destination: molt/migrate-resume-replication.md
sources: ['molt/migrate-replicate-only.md']
- destination: molt/migration-overview.md
sources: [':version/migration-overview.md']
- destination: molt/migration-overview.md
sources: ['molt/molt-overview.md']
- destination: molt/migration-overview.md
sources: ['import-data.md']
versions: ['v2.1', 'v19.1', 'v20.1', 'v20.2', 'v21.1']
- destination: molt/migration-overview.md
sources:
- molt/live-migration-service.md
- :version/live-migration-service.md
- destination: molt/molt-fetch.md
sources: [':version/molt-fetch.md']
- destination: molt/molt-verify.md
sources: [':version/molt-verify.md']
- destination: node-shutdown.md
sources: ['cockroach-quit.md']
versions: ['v21.2']
- destination: node-shutdown.md?filters=decommission
sources: ['remove-nodes.md']
versions: ['v21.2']
- destination: orchestrate-cockroachdb-with-kubernetes-multi-cluster.md
sources: ['orchetrate-cockroachdb-with-kubernetes-multi-region.md']
versions: ['v2.0', 'v2.1', 'v19.1', 'v20.1', 'v20.2', 'v21.1']
- destination: performance-benchmarking-with-tpc-c-1k-warehouses.md
sources: ['performance-benchmarking-with-tpc-c.md']
versions: ['v20.1']
- destination: performance-benchmarking-with-tpcc-large.md
sources: ['performance-benchmarking-with-tpc-c-100k-warehouses.md']
versions: ['v20.2', 'v21.1']
- destination: performance-benchmarking-with-tpcc-local.md
sources: ['performance-benchmarking-with-tpc-c-10-warehouses.md']
versions: ['v20.2', 'v21.1']
- destination: performance-benchmarking-with-tpcc-medium.md
sources: ['performance-benchmarking-with-tpc-c-10k-warehouses.md']
versions: ['v20.2', 'v21.1']
- destination: performance-benchmarking-with-tpcc-small.md
sources: ['performance-benchmarking-with-tpc-c-1k-warehouses.md']
versions: ['v20.2', 'v21.1']
- destination: postgresql-compatibility.md
sources: ['porting-postgres.md']
versions: ['v20.1', 'v20.2', 'v21.1']
- destination: regional-tables.md
sources:
- topology-geo-partitioned-leaseholders.md
- topology-geo-partitioned-replicas.md
versions: ['v21.1', 'v21.2', 'v22.1', 'v22.2', 'v23.1']
- destination: revoke.md
sources: ['revoke-roles.md']
versions: ['v21.1']
- destination: scalar-expressions.md
sources: ['sql-expressions.md']
versions: ['v2.0', 'v2.1', 'v19.1', 'v20.1', 'v20.2', 'v21.1']
- destination: select-clause.md
sources: ['select.md']
versions: ['v2.0', 'v2.1', 'v19.1', 'v20.1', 'v20.2', 'v21.1']
- destination: selection-queries.md
sources: ['selection-clauses.md']
versions: ['v2.0', 'v2.1', 'v19.1', 'v20.1', 'v20.2', 'v21.1']
- destination: serverless-faqs.md
sources: ['free-faqs.md']
versions: ['cockroachcloud']
- destination: set-vars.md
sources:
- set-application-name.md
- set-database.md
- set-time-zone.md
versions: [':version']
- destination: show-create.md
sources:
- show-create-sequence.md
- show-create-table.md
- show-create-view.md
versions: ['v2.1', 'v19.1', 'v20.1', 'v20.2', 'v21.1']
- destination: show-experimental-ranges.md
sources: ['show-testing-ranges.md']
versions: ['v2.0', 'v2.1', 'v19.1']
- destination: show-ranges.md
sources: ['show-experimental-ranges.md']
versions: ['v20.1', 'v20.2', 'v21.1']
- destination: show-statements.md
sources: ['show-queries.md']
versions: ['v21.1']
- destination: show-vars.md
sources:
- show-all.md
- show-time-zone.md
- show-transaction.md
versions: [':version']
- destination: stable/build-a-python-app-with-cockroachdb-psycopg3
sources:
- v20.1/build-a-python-app-with-cockroachdb-pony.md
- destination: stable/install-client-drivers.md
sources: ['install-client-drivers.md']
- destination: stable/licensing-faqs.md
sources: [':version/licensing.md']
- destination: start-a-local-cluster-in-docker-mac.md
sources: ['start-a-local-cluster-in-docker.md']
versions: ['v20.1', 'v20.2', 'v21.1']
- destination: stream-data-out-of-cockroachdb-using-changefeeds.md
sources: ['change-data-capture.md']
versions: ['v20.2', 'v21.1']
- destination: take-and-restore-self-managed-backups.md
sources: ['run-bulk-operations.md', 'take-and-restore-customer-owned-backups.md']
versions: ['cockroachcloud']
- destination: take-full-and-incremental-backups.md
sources:
- back-up-data.md
- backup-and-restore-advanced-options.md
- backup-and-restore.md
- restore-data.md
versions: ['v20.2', 'v21.1']
- destination: tools-page.md
sources: ['monitoring-page.md']
versions: ['cockroachcloud']
- destination: topology-patterns.md
sources: ['cluster-topology-patterns.md']
versions: ['v19.1', 'v20.1', 'v20.2', 'v21.1']
- destination: ui-cdc-dashboard.md
sources: ['admin-ui-cdc-dashboard.md']
versions: ['v20.2', 'v21.1']
- destination: ui-cluster-overview-page.md
sources: ['admin-ui-cluster-overview-page.md']
versions: ['v20.2', 'v21.1']
- destination: ui-custom-chart-debug-page.md
sources: ['admin-ui-custom-chart-debug-page.md']
versions: ['v20.2', 'v21.1']
- destination: ui-databases-page.md
sources: ['admin-ui-databases-page.md']
versions: ['v20.2', 'v21.1']
- destination: ui-debug-pages.md
sources: ['admin-ui-debug-pages.md']
versions: ['v20.2', 'v21.1']
- destination: ui-hardware-dashboard.md
sources: ['admin-ui-hardware-dashboard.md']
versions: ['v20.2', 'v21.1']
- destination: ui-jobs-page.md
sources: ['admin-ui-jobs-page.md']
versions: ['v20.2', 'v21.1']
- destination: ui-network-latency-page.md
sources: ['admin-ui-network-latency-page.md']
versions: ['v20.2', 'v21.1']
- destination: ui-overview-dashboard.md
sources: ['admin-ui-overview-dashboard.md']
versions: ['v20.2', 'v21.1']
- destination: ui-overview.md
sources:
- admin-ui-access-and-navigate.md
- admin-ui-overview.md
- explore-the-admin-ui.md
versions: ['v20.2', 'v21.1']
- destination: ui-replication-dashboard.md
sources: ['admin-ui-replication-dashboard.md']
versions: ['v20.2', 'v21.1']
- destination: ui-runtime-dashboard.md
sources: ['admin-ui-runtime-dashboard.md']
versions: ['v20.2', 'v21.1']
- destination: ui-sessions-page.md
sources: ['admin-ui-sessions-page.md']
versions: ['v20.2', 'v21.1']
- destination: ui-sql-dashboard.md
sources: ['admin-ui-sql-dashboard.md']
versions: ['v20.2', 'v21.1']
- destination: ui-statements-page.md
sources: ['admin-ui-statements-page.md']
versions: ['v20.2', 'v21.1']
- destination: ui-storage-dashboard.md
sources: ['admin-ui-storage-dashboard.md']
versions: ['v20.2', 'v21.1']
- destination: ui-top-ranges-page.md
sources: ['ui-hot-ranges-page.md']
versions: ['v25.4']
- destination: use-a-local-file-server-for-bulk-operations.md
sources: ['create-a-file-server.md']
versions: ['v20.2', 'v21.1']
- destination: use-a-local-file-server.md
sources: ['use-a-local-file-server-for-bulk-operations.md']
versions: ['v22.2', 'v23.1']
- destination: use-cloud-storage.md
sources: ['use-cloud-storage-for-bulk-operations.md']
versions: ['v22.2', 'v23.1']
- destination: managed-backups.md
sources: ['backups-page.md', 'use-managed-service-backups.md']
versions: ['cockroachcloud']
- destination: use-userfile-storage.md
sources: ['use-userfile-for-bulk-operations.md']
versions: ['v22.2', 'v23.1']
# Removed Pages
- destination: ../releases/v25.4.md#known-limitations
sources: ['known-limitations.md']
versions: ['v25.4']
- destination: licensing-faqs.md
sources: ['enterprise-licensing.md']
versions: ['v23.1', 'v23.2', 'v24.1', 'v24.2', 'v24.3']
- destination: :version/licensing-faqs.md
sources: [':version/get-started-with-enterprise-trial.md']
- destination: movr.md#develop-and-deploy-a-global-application
sources: ['movr-flask-overview.md']
versions: ['v23.1']
- destination: :version/collate.md
sources: [':version/collatedstring.md']
- destination: :version/sql-feature-support.md
sources: [':version/detailed-sql-support.md']
- destination: admission-control.md
sources: ['architecture/admission-control.md']
versions: ['v22.1']
- destination: alter-database.md
sources: ['convert-to-schema.md']
versions: ['v22.1']
- destination: alter-database.md#add-region
sources: ['add-region.md']
versions: ['v22.2']
- destination: alter-database.md#add-super-region
sources: ['add-super-region.md']
versions: ['v22.2']
- destination: alter-database.md#alter-locality
sources: ['alter-locality.md']
versions: ['v22.2']
- destination: alter-database.md#alter-super-region
sources: ['alter-super-region.md']
versions: ['v22.2']
- destination: alter-database.md#drop-region
sources: ['drop-region.md']
versions: ['v22.2']
- destination: alter-database.md#drop-secondary-region
sources: ['drop-secondary-region.md']
versions: ['v22.2']
- destination: alter-database.md#drop-super-region
sources: ['drop-super-region.md']
versions: ['v22.2']
- destination: alter-database.md#placement
sources: ['placement-restricted.md']
versions: ['v22.2']
- destination: alter-database.md#rename-to
sources: ['rename-database.md']
versions: ['v22.2']
- destination: alter-database.md#set-primary-region
sources: ['set-primary-region.md']
versions: ['v22.2']
- destination: alter-database.md#set-secondary-region
sources: ['set-secondary-region.md']
versions: ['v22.2']
- destination: alter-database.md#survive-zone-region-failure
sources: ['survive-failure.md']
versions: ['v22.2']
- destination: alter-index.md#rename-to
sources: ['rename-index.md']
versions: ['v22.2']
- destination: alter-range.md#relocate
sources: ['alter-range-relocate.md']
versions: ['v22.2']
- destination: alter-sequence.md
sources: ['rename-sequence.md']
versions: ['v21.1']
- destination: alter-table.md#add-column
sources: ['add-column.md']
versions: ['v22.2']
- destination: alter-table.md#add-constraint
sources: ['add-constraint.md']
versions: ['v22.2']
- destination: alter-table.md#alter-column
sources: ['alter-column.md']
versions: ['v22.2']
- destination: alter-table.md#alter-primary-key
sources: ['alter-primary-key.md']
versions: ['v22.2']
- destination: alter-table.md#drop-column
sources: ['drop-column.md']
versions: ['v22.2']
- destination: alter-table.md#drop-constraint
sources: ['drop-constraint.md']
versions: ['v22.2']
- destination: alter-table.md#experimental_audit
sources: ['experimental-audit.md']
versions: ['v22.2']
- destination: alter-table.md#owner-to
sources: ['owner-to.md']
versions: ['v22.2']
- destination: alter-table.md#rename-column
sources: ['rename-column.md']
versions: ['v22.2']
- destination: alter-table.md#rename-constraint
sources: ['rename-constraint.md']
versions: ['v22.2']
- destination: alter-table.md#rename-to
sources: ['rename-table.md']
versions: ['v22.2']
- destination: alter-table.md#reset-storage-parameter
sources: ['reset-storage-parameter.md']
versions: ['v22.2']
- destination: alter-table.md#set-locality
sources: ['set-locality.md']
versions: ['v22.2']
- destination: alter-table.md#set-storage-parameter
sources: ['set-storage-parameter.md']
versions: ['v22.2']
- destination: alter-table.md#split-at
sources: ['split-at.md']
versions: ['v22.2']
- destination: alter-table.md#unsplit-at
sources: ['unsplit-at.md']
versions: ['v22.2']
- destination: alter-table.md#validate-constraint
sources: ['validate-constraint.md']
versions: ['v22.2']
- destination: architecture/glossary.md
sources: ['spatial-glossary.md']
versions: ['v23.1']
- destination: change-data-capture-overview.md
sources: ['stream-data-out-of-cockroachdb-using-changefeeds.md']
versions: ['v21.2', 'v22.1', 'v22.2', 'v23.1']
- destination: changefeed-messages.md
sources: ['use-changefeeds.md']
versions: ['v22.1']
- destination: cockroachcloud/cmek.md#faq
sources: ['cockroachcloud/cmek-faq.md']
- destination: cockroachcloud/managing-cmek.md
sources: ['cockroachcloud/cmek-ops-*.md']
- destination: cockroachcloud/connect-to-your-cluster.md
sources: ['cockroachcloud/stable/cockroachcloud-connect-to-your-cluster.md']
- destination: cockroachcloud/create-your-cluster.md
sources: ['cockroachcloud/stable/cockroachcloud-create-your-cluster.md']
- destination: cockroachcloud/quickstart.md
sources:
- :version/deploy-a-test-cluster.md
- :version/hello-world-go-gorm.md
- :version/hello-world-go-pgx.md
- :version/hello-world-java-jdbc.md
- :version/hello-world-node-postgres.md
- :version/hello-world-python-sqlalchemy.md
- destination: cockroachcloud/serverless-resource-usage.md
sources: ['cockroachcloud/serverless-benchmarking.md']
- destination: upgrade-cockroach-version.md
sources: 'upgrade-to-v*.md'
versions: ['cockroachcloud']
- destination: community-tooling.md
sources:
- build-a-c++-app-with-cockroachdb.md
- build-a-clojure-app-with-cockroachdb.md
- build-a-php-app-with-cockroachdb.md
versions: ['v20.2', 'v21.1', 'v21.2']
- destination: configure-replication-zones.md
sources: ['configure-zone.md']
versions: ['v22.2']
- destination: create-schema.md
sources: ['convert-to-schema.md']
versions: ['v22.1']
- destination: example-apps.md
sources: ['hello-world-example-apps.md']
versions: ['v20.2', 'v21.1', 'v21.2', 'v22.1', 'cockroachcloud']
- destination: frequently-asked-questions.md
sources:
- automated-scaling-and-repair.md
- distributed-transactions.md
- go-implementation.md
- high-availability.md
- open-source.md
- simplified-deployment.md
- sql.md
- strong-consistency.md
versions: ['v19.1', 'v20.1', 'v20.2', 'v21.1']
- destination: https://docs.peewee-orm.com/en/latest/peewee/playhouse.html
sources: [':version/build-a-python-app-with-cockroachdb-peewee.md']
- destination: https://wiki.crdb.io/wiki/spaces/CRDB/pages/73204033/Contributing+to+CockroachDB
sources: [':version/contribute-to-cockroachdb.md']
force: true
- destination: make-queries-fast.md
sources: ['performance-tuning.md']
versions: ['v21.1']
- destination: make-queries-fast.md
sources: ['performance-features-overview.md']
versions: ['v23.1']
- destination: movr.md#develop-and-deploy-a-global-application
sources: ['movr-flask-overview.md']
versions: ['v23.1']
- destination: multiregion-survival-goals.md
sources: ['when-to-use-zone-vs-region-survival-goals.md']
versions: ['v23.1']
- destination: partitioning.md
sources: ['partition-by.md']
versions: ['v22.2']
- destination: query-behavior-troubleshooting.md
sources: ['error-handling-and-troubleshooting.md']
versions: ['v23.1']
- destination: query-spatial-data.md
sources: ['spatial-data.md']
versions: ['v23.1']
- destination: schema-design-update.md
sources: ['set-schema.md']
versions: ['v22.2']
- destination: show-create.md
sources: ['cockroach-dump.md']
versions: ['v21.2', 'v22.1']
- destination: spatial-data-overview.md
sources: ['spatial-features.md']
versions: ['v23.1']
- destination: stable/build-a-python-app-with-cockroachdb.md
sources: ['tutorials/build-a-python-app-with-cockroachdb-interactive.md']
- destination: stable/cockroach-sql.md
sources: ['use-the-built-in-sql-client.md']
- destination: stable/column-families.md
sources: ['column-families.md']
- destination: stable/configure-replication-zones.md
sources: ['configure-replication-zones.md']
- destination: stable/frequently-asked-questions.md
sources:
- automated-scaling-and-repair.md
- frequently-asked-questions.md
- sql.md
- destination: stable/kubernetes-overview.md
sources:
- v21.1/orchestrate-cockroachdb-with-docker-swarm.md
- v21.2/orchestrate-cockroachdb-with-docker-swarm.md
- v22.1/orchestrate-cockroachdb-with-docker-swarm.md
- dev/orchestrate-cockroachdb-with-docker-swarm.md
- orchestrate-cockroachdb-with-docker-swarm.md
- stable/orchestrate-cockroachdb-with-docker-swarm.md
- :version/orchestrate-cockroachdb-with-mesosphere-insecure.md
- destination: stable/performance-recipes.md
sources: ['performance-recipes.md']
- destination: stable/show-vars.md
sources: ['show-database.md']
- destination: stable/start-a-local-cluster.md
sources: ['start-a-local-cluster.md']
- destination: table-localities.md
sources: ['when-to-use-regional-vs-global-tables.md']
versions: ['v23.1']
- destination: topology-follow-the-workload.md
sources: ['demo-follow-the-workload.md']
versions: ['v20.1', 'v20.2']
- destination: tutorials/sql-playground.md
sources:
- :version/sql-playground.md
- sql-playground.md
- destination: v21.1/interleave-in-parent.md#deprecation
sources:
- dev/interleave-in-parent.md
- interleave-in-parent.md
- stable/interleave-in-parent.md
# Cloud 2.0 updates (Serverless/Dedicated to Basic/Standard/Advanced)
- destination: cockroachcloud/cockroachdb-advanced-on-azure.md
sources: ['cockroachcloud/cockroachdb-dedicated-on-azure.md']
- destination: cockroachcloud/create-a-basic-cluster.md
sources: ['cockroachcloud/create-a-serverless-cluster.md']
versions: ['cockroachcloud']
- destination: cockroachcloud/basic-cluster-management.md
sources: ['cockroachcloud/serverless-cluster-management.md']
versions: ['cockroachcloud']
- destination: cockroachcloud/advanced-cluster-management.md
sources: ['cockroachcloud/cluster-management-advanced.md']
versions: ['cockroachcloud']
- destination: cockroachcloud/connect-to-a-basic-cluster.md
sources: ['cockroachcloud/connect-to-a-serverless-cluster.md']
- destination: cockroachcloud/resource-usage.md
sources: ['cockroachcloud/serverless-resource-usage.md']
- destination: plan-your-cluster-basic.md
sources:
- 'plan-your-cluster-serverless.md'
- 'planning-your-serverless-cluster.md'
- 'learn-about-pricing.md'
- 'learn-about-request-units.md'
versions: ['cockroachcloud']
- destination: index.md
sources:
- 'serverless-faqs.md'
- 'choose-a-deployment-option.md'
# Cloud releases
- destination: releases/cloud.md#january-22-2021
sources: ['releases/cockroachcloud-01222021.md']
- destination: releases/cloud.md#january-10-2022
sources: ['releases/cockroachcloud-01102022.md']
- destination: releases/cloud.md#february-09-2021
sources: ['releases/cockroachcloud-02092021.md']
- destination: releases/cloud.md#february-02-2020
sources: ['releases/cockroachcloud-03022020.md']
- destination: releases/cloud.md#march-08-2021
sources: ['releases/cockroachcloud-03082021.md']
- destination: releases/cloud.md#april-05-2021
sources: ['releases/cockroachcloud-04052021.md']
- destination: releases/cloud.md#april-06-2020
sources: ['releases/cockroachcloud-04062020.md']
- destination: releases/cloud.md#may-03-2021
sources: ['releases/cockroachcloud-05032021.md']
- destination: releases/cloud.md#may-04-2020
sources: ['releases/cockroachcloud-05042020.md']
- destination: releases/cloud.md#june-07-2021
sources: ['releases/cockroachcloud-06072021.md']
- destination: releases/cloud.md#june-11-2020
sources: ['releases/cockroachcloud-06112020.md']
- destination: releases/cloud.md#july-06-2021
sources: ['releases/cockroachcloud-07062021.md']
- destination: releases/cloud.md#july-06-2020
sources: ['releases/cockroachcloud-07062020.md']
- destination: releases/cloud.md#august-09-2021
sources: ['releases/cockroachcloud-08092021.md']
- destination: releases/cloud.md#september-07-2021
sources: ['releases/cockroachcloud-09072021.md']
- destination: releases/cloud.md#october-04-2021
sources: ['releases/cockroachcloud-10042021.md']
- destination: releases/cloud.md#november-08-2021
sources: ['releases/cockroachcloud-11082021.md']
- destination: releases/cloud.md#november-19-2020
sources: ['releases/cockroachcloud-11192020.md']
- destination: releases/cloud.md#december-06-2021
sources: ['releases/cockroachcloud-12062021.md']
- destination: releases/cloud.md#december-11-2020
sources: ['releases/cockroachcloud-12112020.md']
- destination: releases/cloud.md
sources: ['releases/index-cockroachcloud.md']
# Redirects for Homebrew
- destination: stable/secure-a-cluster.md
sources: ['secure-a-cluster.md']
# Redirects for Dockerhub
- destination: stable/deploy-cockroachdb-with-kubernetes.md
sources: ['orchestrate-cockroachdb-with-kubernetes.md']
- destination: stable/install-cockroachdb.md
sources: ['install-cockroachdb.md']
- destination: stable/install-cockroachdb-mac
sources: ['stable/install-cockroachdb/install-cockroachdb-mac']
- destination: stable/install-cockroachdb-windows
sources: ['stable/install-cockroachdb/install-cockroachdb-windows']
- destination: stable/install-cockroachdb-linux
sources: ['stable/install-cockroachdb/install-cockroachdb-linux']
- destination: stable/start-a-local-cluster-in-docker-linux.md
sources: ['start-a-local-cluster-in-docker.md']
# Redirects from jekyll-redirect-from gem
- destination: deploy-cockroachdb-with-kubernetes.md
sources: ['orchestrate-cockroachdb-with-kubernetes.md']
versions: ['v21.1', 'v21.2', 'v22.1', 'v22.2']
- destination: deploy-cockroachdb-with-kubernetes-insecure.md
sources: ['orchestrate-cockroachdb-with-kubernetes-insecure.md']
versions: ['v21.1', 'v21.2', 'v22.1', 'v22.2']
- destination: import-into.md
sources:
- import.md
- cockroach-import.md
versions: ['v24.1', 'v24.2']
- destination: kubernetes-overview.md
sources: ['orchestration.md']
versions: ['v21.1', 'v21.2', 'v22.1']
- destination: movr-flask-application.md
sources: ['multi-region-application.md']
versions: ['v21.1', 'v21.2', 'v22.1', 'v22.2']
- destination: movr-flask-database.md
sources: ['multi-region-database.md']
versions: ['v21.1', 'v21.2', 'v22.1', 'v22.2']
- destination: movr-flask-deployment.md
sources: ['multi-region-deployment.md']
versions: ['v21.1', 'v21.2', 'v22.1', 'v22.2']
- destination: movr-flask-overview.md
sources: ['multi-region-overview.md']
versions: ['v21.1', 'v21.2', 'v22.1', 'v22.2']
- destination: movr-flask-setup.md
sources: ['multi-region-setup.md']
versions: ['v21.1', 'v21.2', 'v22.1', 'v22.2']
- destination: movr-flask-use-case.md
sources: ['multi-region-use-case.md']
versions: ['v21.1', 'v21.2', 'v22.1', 'v22.2']
- destination: serverless-resource-usage.md
sources: ['optimize-serverless-workload.md']
versions: ['cockroachcloud']
- destination: https://www.cockroachlabs.com/compare/
sources:
- stable/cockroachdb-in-comparison.md
- v23.1/cockroachdb-in-comparison.md
- v23.2/cockroachdb-in-comparison.md
- v24.1/cockroachdb-in-comparison.md
- v24.2/cockroachdb-in-comparison.md
- v24.3/cockroachdb-in-comparison.md
- v25.1/cockroachdb-in-comparison.md
# page deletion project
- destination: stable/sql-statements.md
sources: ['cockroachcloud/learn-cockroachdb-sql.md']
- destination: cockroachcloud/client-certs-advanced.md
sources: ['v26.1/security-reference/config-secure-hba.md', 'stable/security-reference/config-secure-hba.md', 'v26.2/security-reference/config-secure-hba.md']
- destination: cockroachdb-operator-overview.md
sources: ['orchestrate-a-local-cluster-with-kubernetes.md', 'orchestrate-a-local-cluster-with-kubernetes-insecure.md']
versions: ['v26.1', 'v26.2']
- destination: deploy-cockroachdb-on-premises.md
sources: ['deploy-cockroachdb-on-premises-insecure.md']
versions: ['v26.1', 'v26.2']
- destination: deploy-cockroachdb-on-aws.md
sources: ['deploy-cockroachdb-on-aws-insecure.md']
versions: ['v26.1', 'v26.2']
- destination: deploy-cockroachdb-on-microsoft-azure.md
sources: ['deploy-cockroachdb-on-microsoft-azure-insecure.md']
versions: ['v26.1', 'v26.2']
- destination: deploy-cockroachdb-on-google-cloud-platform.md
sources: ['deploy-cockroachdb-on-google-cloud-platform-insecure.md']
versions: ['v26.1', 'v26.2']
- destination: deploy-cockroachdb-on-digital-ocean.md
sources: ['deploy-cockroachdb-on-digital-ocean-insecure.md']
versions: ['v26.1', 'v26.2']
- destination: stable/developer-guide-overview.md
sources: ['cockroachcloud/deploy-a-python-to-do-app-with-flask-kubernetes-and-cockroachcloud.md']
- destination: developer-guide-overview.md
sources: ['example-apps.md', 'build-a-spring-app-with-cockroachdb-jdbc.md', 'build-a-spring-app-with-cockroachdb-jpa.md', 'movr-flask-use-case.md', 'movr-flask-database.md', 'movr-flask-setup.md', 'movr-flask-application.md', 'movr-flask-deployment.md']
versions: ['v26.1', 'v26.2']
- destination: topology-patterns.md
sources: ['topology-development.md']
versions: ['v26.1', 'v26.2']
- destination: monitoring-and-alerting.md
sources: ['datadog.md', 'dbmarlin.md', 'kibana.md']
versions: ['v26.1', 'v26.2']
- destination: schema-design-overview.md
sources: ['schema-design-database.md', 'schema-design-schema.md', 'schema-design-table.md', 'schema-design-update.md']
versions: ['v26.1', 'v26.2']
- destination: reads-and-writes-overview.md
sources: ['query-data.md']
versions: ['v26.1', 'v26.2']
- destination: cockroachcloud/overview-page.md
sources: ['cockroachcloud/cluster-overview-page.md']
- destination: releases/index.md
sources: ['releases/staged-release-process.md']
- destination: releases/downloads-archive.md
sources: ['releases/unsupported-versions.md']
- destination: delete.md
sources: ['delete-data.md']
versions: ['v26.1', 'v26.2']
- destination: configure-replication-zones.md
sources: ['demo-automatic-cloud-migration.md']
versions: ['v26.1', 'v26.2']
- destination: jsonb.md
sources: ['demo-json-support.md']
versions: ['v26.1', 'v26.2']
- destination: query-spatial-data.md
sources: ['export-spatial-data.md']
versions: ['v26.1', 'v26.2']
- destination: insert.md
sources: ['insert-data.md']
versions: ['v26.1', 'v26.2']
- destination: spatial-data-overview.md
sources: ['spatial-tutorial.md', 'geoserver.md']
versions: ['v26.1', 'v26.2']
- destination: update.md
sources: ['update-data.md']
versions: ['v26.1', 'v26.2']
- destination: cockroachcloud/byoc-azure-deployment.md
sources: ['cockroachcloud/byoc-deployment.md']
- destination: molt/migration-approach-classic-bulk-load.md
sources: ['molt/migrate-bulk-load.md']
- destination: molt/migration-approach-delta.md
sources: ['molt/migrate-load-replicate.md']
- destination: molt/molt-replicator.md#resume-after-an-interruption
sources: ['molt/migrate-resume-replication.md']
- destination: molt/molt-replicator.md#failback-replication
sources: ['molt/migrate-failback.md']
- destination: multiregion-overview.md
sources: ['demo-low-latency-multi-region-deployment.md', 'migrate-to-multiregion-sql.md']
versions: ['v26.1', 'v26.2']
- destination: performance-best-practices-overview.md
sources: ['performance.md', 'performance-benchmarking-with-tpcc-local.md', 'performance-benchmarking-with-tpcc-small.md', 'performance-benchmarking-with-tpcc-medium.md', 'performance-benchmarking-with-tpcc-large.md', 'performance-benchmarking-with-tpcc-local-multiregion.md']
versions: ['v26.1', 'v26.2']
- destination: support-resources.md
sources: ['file-an-issue.md']
versions: ['v26.1', 'v26.2']
---
## File: src/current/_data/settings_main_nav.yml
main_nav_global:
customer_top:
image: https://crl2020.imgix.net/img/lush-22.png?h=0.5
text: CockroachDB gives Lush a global database for 950 stores across 49 countries
link: https://resources.cockroachlabs.com/case-study/lush-case-study
customer_bottom:
image: https://crl2020.imgix.net/img/nubank_logo_purple-44.png?h=0.5
text: Nubank serves 34 million customers with banking apps powered by CockroachDB
link: https://www.cockroachlabs.com/blog/nubank/
---
## File: src/current/_data/v24.2/metrics/child-metrics.yml
# child-metrics.yml is a manually curated file of metrics that are included in the Child Metrics.
# The tenant.consumption.* metrics are not included because they only apply to serverless.
#
# The corresponding metrics-list.csv file was generated using the v24.1.0 binary with the following command:
# cockroach gen metric-list --format=csv > metrics-list.csv
# Once generated, the metrics-list.csv was manually modified to change the case of the headers to lowercase to work with liquid comparison code.
- child_metric_id: changefeed.error_retries
feature: changefeed
- child_metric_id: changefeed.emitted_messages
feature: changefeed
- child_metric_id: changefeed.emitted_batch_sizes
feature: changefeed
- child_metric_id: changefeed.filtered_messages
feature: changefeed
- child_metric_id: changefeed.message_size_hist
feature: changefeed
- child_metric_id: changefeed.emitted_bytes
feature: changefeed
- child_metric_id: changefeed.flushed_bytes
feature: changefeed
- child_metric_id: changefeed.flushes
feature: changefeed
- child_metric_id: changefeed.size_based_flushes
feature: changefeed
- child_metric_id: changefeed.parallel_io_queue_nanos
feature: changefeed
- child_metric_id: changefeed.parallel_io_pending_rows
feature: changefeed
- child_metric_id: changefeed.parallel_io_result_queue_nanos
feature: changefeed
- child_metric_id: changefeed.parallel_io_in_flight_keys
feature: changefeed
- child_metric_id: changefeed.sink_io_inflight
feature: changefeed
- child_metric_id: changefeed.sink_batch_hist_nanos
feature: changefeed
- child_metric_id: changefeed.flush_hist_nanos
feature: changefeed
- child_metric_id: changefeed.commit_latency
feature: changefeed
- child_metric_id: changefeed.admit_latency
feature: changefeed
- child_metric_id: changefeed.backfill_count
feature: changefeed
- child_metric_id: changefeed.backfill_pending_ranges
feature: changefeed
- child_metric_id: changefeed.running
feature: changefeed
- child_metric_id: changefeed.batch_reduction_count
feature: changefeed
- child_metric_id: changefeed.internal_retry_message_count
feature: changefeed
- child_metric_id: changefeed.schema_registry.retry_count
feature: changefeed
- child_metric_id: changefeed.schema_registry.registrations
feature: changefeed
- child_metric_id: changefeed.aggregator_progress
feature: changefeed
- child_metric_id: changefeed.checkpoint_progress
feature: changefeed
- child_metric_id: changefeed.lagging_ranges
feature: changefeed
- child_metric_id: changefeed.cloudstorage_buffered_bytes
feature: changefeed
- child_metric_id: changefeed.kafka_throttling_hist_nanos
feature: changefeed
- child_metric_id: livebytes
feature: virtual
- child_metric_id: keybytes
feature: virtual
- child_metric_id: valbytes
feature: virtual
- child_metric_id: rangekeybytes
feature: virtual
- child_metric_id: rangevalbytes
feature: virtual
- child_metric_id: totalbytes
feature: virtual
- child_metric_id: intentbytes
feature: virtual
- child_metric_id: lockbytes
feature: virtual
- child_metric_id: livecount
feature: virtual
- child_metric_id: keycount
feature: virtual
- child_metric_id: valcount
feature: virtual
- child_metric_id: rangekeycount
feature: virtual
- child_metric_id: rangevalcount
feature: virtual
- child_metric_id: intentcount
feature: virtual
- child_metric_id: lockcount
feature: virtual
- child_metric_id: intentage
feature: virtual
- child_metric_id: gcbytesage
feature: virtual
- child_metric_id: sysbytes
feature: virtual
- child_metric_id: syscount
feature: virtual
- child_metric_id: abortspanbytes
feature: virtual
- child_metric_id: kv.tenant_rate_limit.num_tenants
feature: virtual
- child_metric_id: kv.tenant_rate_limit.current_blocked
feature: virtual
- child_metric_id: kv.tenant_rate_limit.read_batches_admitted
feature: virtual
- child_metric_id: kv.tenant_rate_limit.write_batches_admitted
feature: virtual
- child_metric_id: kv.tenant_rate_limit.read_requests_admitted
feature: virtual
- child_metric_id: kv.tenant_rate_limit.write_requests_admitted
feature: virtual
- child_metric_id: kv.tenant_rate_limit.read_bytes_admitted
feature: virtual
- child_metric_id: kv.tenant_rate_limit.write_bytes_admitted
feature: virtual
- child_metric_id: security.certificate.expiration.client
feature: secure
type: GAUGE
unit: SECONDS
- child_metric_id: jobs.row_level_ttl.span_total_duration
feature: row-level-ttl
- child_metric_id: jobs.row_level_ttl.select_duration
feature: row-level-ttl
- child_metric_id: jobs.row_level_ttl.delete_duration
feature: row-level-ttl
- child_metric_id: jobs.row_level_ttl.rows_selected
feature: row-level-ttl
- child_metric_id: jobs.row_level_ttl.rows_deleted
feature: row-level-ttl
- child_metric_id: jobs.row_level_ttl.num_active_spans
feature: row-level-ttl
- child_metric_id: jobs.row_level_ttl.total_rows
feature: row-level-ttl
- child_metric_id: jobs.row_level_ttl.total_expired_rows
feature: row-level-ttl
- child_metric_id: rpc.connection.healthy
feature: all
- child_metric_id: rpc.connection.unhealthy
feature: all
- child_metric_id: rpc.connection.inactive
feature: all
- child_metric_id: rpc.connection.healthy_nanos
feature: all
- child_metric_id: rpc.connection.unhealthy_nanos
feature: all
- child_metric_id: rpc.connection.heartbeats
feature: all
- child_metric_id: rpc.connection.failures
feature: all
- child_metric_id: rpc.connection.avg_round_trip_latency
feature: all
- child_metric_id: logical_replication.catchup_ranges_by_label
feature: ldr
- child_metric_id: logical_replication.events_dlqed_by_label
feature: ldr
- child_metric_id: logical_replication.events_ingested_by_label
feature: ldr
- child_metric_id: logical_replication.replicated_time_by_label
feature: ldr
- child_metric_id: logical_replication.scanning_ranges_by_label
feature: ldr
---
## File: src/current/_data/v24.2/metrics/metrics.yml
# metrics.yml is a manually curated file of metrics that are included in the Canned Metrics for Serverless deployment.
# The metrics are in the order of appearance in the configuration file:
# https://github.com/cockroachlabs/managed-service/pull/16129/files
# console/assets/js/pages/clusterDetail/metrics/graphConfigs.tsx
# The data for the metrics was also sourced from
# https://github.com/cockroachlabs/docs/blob/main/src/current/_includes/v23.2/essential-metrics.md
#
# The corresponding metrics-list.csv file was generated using the v23.2.0 binary with the following command:
# cockroach gen metric-list --format=csv > metrics-list.csv
# Once generated, the metrics-list.csv was manually modified to change the case of the headers to lowercase to work with liquid comparison code.
- metric_id: sql.new_conns
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Connections Per Second"
datadog_id_selfhosted: sql.new_conns.count
essential: true
metric_type: SQL
metric_ui_tab: [ Overview, SQL ]
metric_ui_graph: "SQL Connections"
- metric_id: sql.select.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Select"
datadog_id_selfhosted: sql.select.count
datadog_id_dedicated: sql.select.count
essential: true
metric_type: SQL
metric_ui_tab: [ Overview, SQL ]
metric_ui_graph: "SQL Statements"
- metric_id: sql.update.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Update"
datadog_id_selfhosted: sql.update.count
datadog_id_dedicated: sql.update.count
essential: true
metric_type: SQL
metric_ui_tab: [ Overview, SQL ]
metric_ui_graph: "SQL Statements"
- metric_id: sql.insert.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Insert"
datadog_id_selfhosted: sql.insert.count
datadog_id_dedicated: sql.insert.count
essential: true
metric_type: SQL
metric_ui_tab: [ Overview, SQL ]
metric_ui_graph: "SQL Statements"
- metric_id: sql.delete.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Delete"
datadog_id_selfhosted: sql.delete.count
datadog_id_dedicated: sql.delete.count
essential: true
metric_type: SQL
metric_ui_tab: [ Overview, SQL ]
metric_ui_graph: "SQL Statements"
- metric_id: sql.service.latency
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "P90, P99, P99.9, P99.99"
datadog_id_selfhosted: sql.service.latency
datadog_id_dedicated: sql.service.latency
essential: true
metric_type: SQL
metric_ui_tab: [ Overview, SQL ]
metric_ui_graph: "Service Latency: SQL Statements"
- metric_id: tenant.consumption.request_units
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "RU, Average RUs"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ Overview, "Request Units"]
metric_ui_graph: "Request Units"
- metric_id: livebytes
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Storage usage"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: Storage
metric_ui_tab: [ Overview ]
metric_ui_graph: Storage
- metric_id: tenant.consumption.sql_pods_cpu_seconds
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Total amount of CPU used by SQL pods"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ "Request Units" ]
metric_ui_graph: "CPU"
- metric_id: tenant.consumption.pgwire_egress_bytes
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Client traffic"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ "Request Units" ]
metric_ui_graph: "Egress"
- metric_id: tenant.consumption.external_io_egress_bytes
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Bulk I/O operations"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ "Request Units" ]
metric_ui_graph: "Egress"
- metric_id: tenant.consumption.read_requests
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Requests"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ "Request Units" ]
metric_ui_graph: "Reads"
- metric_id: tenant.consumption.read_batches
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Batches"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ "Request Units" ]
metric_ui_graph: "Reads"
- metric_id: tenant.consumption.read_bytes
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Bytes"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ "Request Units" ]
metric_ui_graph: "Reads"
- metric_id: tenant.consumption.write_requests
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Requests"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ "Request Units" ]
metric_ui_graph: "Writes"
- metric_id: tenant.consumption.write_batches
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Batches"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ "Request Units" ]
metric_ui_graph: "Writes"
- metric_id: tenant.consumption.write_bytes
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Bytes"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ "Request Units" ]
metric_ui_graph: "Writes"
- metric_id: tenant.consumption.cross_region_network_ru
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Network traffic"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ "Request Units" ]
metric_ui_graph: "Cross-region Networking"
- metric_id: sql.conn.latency
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "P90, P99"
datadog_id_selfhosted: sql.conn.latency
datadog_id_dedicated: sql.conn.latency
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Connection Latency"
- metric_id: sql.conns
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Connections"
datadog_id_selfhosted: sql.conns
datadog_id_dedicated: sql.conns
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Open SQL Sessions"
- metric_id: sql.txns.open
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Open Transactions"
datadog_id_selfhosted: sql.txns.open
datadog_id_dedicated: sql.txns.open
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Open SQL Transactions"
- metric_id: sql.txn.begin.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Begin"
datadog_id_selfhosted: sql.txn.begin.count
datadog_id_dedicated: sql.txn.begin.count
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transactions"
- metric_id: sql.txn.commit.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Commits"
datadog_id_selfhosted: sql.txn.commit.count
datadog_id_dedicated: sql.txn.commit.count
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transactions"
- metric_id: sql.txn.rollback.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Rollbacks"
datadog_id_selfhosted: sql.txn.rollback.count
datadog_id_dedicated: sql.txn.rollback.count
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transactions"
- metric_id: sql.txn.abort.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Aborts"
datadog_id_selfhosted: sql.txn.abort.count
datadog_id_dedicated: sql.txn.abort.count
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transactions"
- metric_id: txn.restarts.writetooold
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Write Too Old"
datadog_id_selfhosted: txn.restarts.writetooold
datadog_id_dedicated: txn.restarts.writetooold
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transaction Restarts"
- metric_id: txn.restarts.writetoooldmulti
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Write Too Old (multiple)"
datadog_id_selfhosted: txn.restarts.writetoooldmulti.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transaction Restarts"
- metric_id: txn.restarts.serializable
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Forwarded Timestamp"
datadog_id_selfhosted: txn.restarts.serializable
datadog_id_dedicated: txn.restarts.serializable
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transaction Restarts"
- metric_id: txn.restarts.asyncwritefailure
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Async Consensus Failure"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transaction Restarts"
- metric_id: txn.restarts.readwithinuncertainty
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Read Within Uncertainty Interval"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transaction Restarts"
- metric_id: txn.restarts.txnaborted
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Aborted"
datadog_id_selfhosted: txn.restarts.txnaborted.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transaction Restarts"
- metric_id: txn.restarts.txnpush
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Push Failure"
datadog_id_selfhosted: txn.restarts.txnpush.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transaction Restarts"
- metric_id: txn.restarts.unknown
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Unknown"
datadog_id_selfhosted: txn.restarts.unknown.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transaction Restarts"
- metric_id: sql.txn.latency
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "P90, P99"
datadog_id_selfhosted: sql.txn.latency
datadog_id_dedicated: sql.txn.latency
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transaction Latency"
- metric_id: sql.statements.active
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Active Statements"
datadog_id_selfhosted: sql.statements.active
datadog_id_dedicated: sql.statements.active
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Active SQL Statements"
- metric_id: sql.failure.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Errors"
datadog_id_selfhosted: sql.failure
datadog_id_dedicated: sql.failure.count
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "SQL Statement Errors"
- metric_id: sql.distsql.contended_queries.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Contention"
datadog_id_selfhosted: sql.distsql.contended.queries
datadog_id_dedicated: sql.distsql.contended.queries
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "SQL Statement Contention"
- metric_id: sql.full.scan.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Full scans"
datadog_id_selfhosted: sql.full.scan
datadog_id_dedicated: sql.full.scan.count
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Full Scans"
- metric_id: sql.ddl.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "DDL Statements"
datadog_id_selfhosted: sql.ddl.count
datadog_id_dedicated: sql.ddl.count
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Schema Changes"
- metric_id: jobs.auto_create_stats.currently_running
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Auto Create Statistics Running"
datadog_id_selfhosted: jobs.auto_create_stats.currently_running
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Table Statistics"
metric_ui_tab: [ SQL, Custom ]
metric_ui_graph: "Statistics Jobs"
- metric_id: jobs.create_stats.currently_running
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Create Statistics Running"
datadog_id_selfhosted: jobs.create_stats.currently_running
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Table Statistics"
metric_ui_tab: [ SQL, Custom ]
metric_ui_graph: "Statistics Jobs"
- metric_id: jobs.auto_create_stats.resume_failed
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Auto Create Statistics Failed"
datadog_id_selfhosted: jobs.auto.create.stats.resume_failed.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Table Statistics"
metric_ui_tab: [ SQL, Custom ]
metric_ui_graph: "Statistics Jobs"
- metric_id: jobs.auto_create_stats.currently_paused
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Auto Create Statistics Paused"
datadog_id_selfhosted: jobs.auto.create.stats.currently_paused
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Table Statistics"
metric_ui_tab: [ SQL, Custom ]
metric_ui_graph: "Statistics Jobs"
- metric_id: changefeed.running
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Running"
datadog_id_selfhosted: changefeed.running
datadog_id_dedicated: changefeed.running
essential: true
metric_type: Changefeeds
metric_ui_tab: [ Changefeeds, Custom ]
metric_ui_graph: "Changefeed Status"
- metric_id: jobs.changefeed.currently_paused
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Paused"
datadog_id_selfhosted: jobs.changefeed.currently_paused
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: Changefeeds
metric_ui_tab: [ Changefeeds, Custom ]
metric_ui_graph: "Changefeed Status"
- metric_id: changefeed.failures
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Failures"
datadog_id_selfhosted: changefeed.failures
datadog_id_dedicated: changefeed.failures
essential: true
metric_type: Changefeeds
metric_ui_tab: [ Changefeeds, Custom ]
metric_ui_graph: "Changefeed Status"
- metric_id: changefeed.error_retries
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Errors"
datadog_id_selfhosted: changefeed.error_retries
datadog_id_dedicated: changefeed.error_retries
essential: true
metric_type: Changefeeds
metric_ui_tab: [ Changefeeds, Custom ]
metric_ui_graph: "Retryable Errors"
- metric_id: changefeed.emitted_messages
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Emitted messages"
datadog_id_selfhosted: changefeed.emitted.messages
datadog_id_dedicated: changefeed.emitted.messages
essential: true
metric_type: Changefeeds
metric_ui_tab: [ Changefeeds, Custom ]
metric_ui_graph: "Emitted Messages"
- metric_id: changefeed.emitted_bytes
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Emitted bytes"
datadog_id_selfhosted: changefeed.emitted_bytes.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: Changefeeds
metric_ui_tab: [ Changefeeds, Custom ]
metric_ui_graph: "Emitted Bytes"
- metric_id: changefeed.commit_latency
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "P99, P90"
datadog_id_selfhosted: changefeed.commit_latency
datadog_id_dedicated: changefeed.commit_latency
essential: true
metric_type: Changefeeds
metric_ui_tab: [ Changefeeds, Custom ]
metric_ui_graph: "Commit Latency"
- metric_id: jobs.changefeed.protected_age_sec
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Protected Timestamp Age"
datadog_id_selfhosted: jobs.changefeed.protected_age_sec
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: Changefeeds
metric_ui_tab: [ Changefeeds, Custom ]
metric_ui_graph: "Oldest Protected Timestamp"
- metric_id: jobs.row_level_ttl.resume_completed
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Resume Completed"
datadog_id_selfhosted: jobs.row_level_ttl.resume_completed.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL", Custom ]
metric_ui_graph: "Row-Level TTL Jobs"
- metric_id: jobs.row_level_ttl.currently_running
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Running"
datadog_id_selfhosted: jobs.row.level.ttl.currently_running
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL", Custom ]
metric_ui_graph: "Row-Level TTL Jobs"
- metric_id: jobs.row_level_ttl.currently_paused
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Paused"
datadog_id_selfhosted: jobs.row_level_ttl.currently_paused
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL", Custom ]
metric_ui_graph: "Row-Level TTL Jobs"
- metric_id: jobs.row_level_ttl.resume_failed
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Resume Failed"
datadog_id_selfhosted: jobs.row_level_ttl.resume_failed.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL", Custom ]
metric_ui_graph: "Row-Level TTL Jobs"
- metric_id: schedules.scheduled-row-level-ttl-executor.failed
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Failed Schedules"
datadog_id_selfhosted: schedules.scheduled-row-level-ttl-executor.failed.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL", Custom ]
metric_ui_graph: "Row-Level TTL Jobs"
- metric_id: jobs.row_level_ttl.rows_selected
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Rows selected"
datadog_id_selfhosted: jobs.row_level_ttl.rows_selected.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL", Custom ]
metric_ui_graph: "Processing Rate"
- metric_id: jobs.row_level_ttl.rows_deleted
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Rows deleted"
datadog_id_selfhosted: jobs.row_level_ttl.rows_deleted.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL", Custom ]
metric_ui_graph: "Processing Rate"
- metric_id: jobs.row_level_ttl.total_rows
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Total Rows"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL" ]
metric_ui_graph: "Estimated Rows"
- metric_id: jobs.row_level_ttl.total_expired_rows
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Expired Rows"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL" ]
metric_ui_graph: "Estimated Rows"
- metric_id: jobs.row_level_ttl.select_duration
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Select Latency (P90), Select Latency (P99)"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL" ]
metric_ui_graph: "Row-Level TTL Job Latency"
- metric_id: jobs.row_level_ttl.delete_duration
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Delete Latency (P90), Delete Latency (P99)"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL" ]
metric_ui_graph: "Row-Level TTL Job Latency"
---
## File: src/current/_data/v24.3/metrics/child-metrics.yml
# child-metrics.yml is a manually curated file of metrics that are included in the Child Metrics.
# The tenant.consumption.* metrics are not included because they only apply to serverless.
#
# The corresponding metrics-list.csv file was generated using the v24.1.0 binary with the following command:
# cockroach gen metric-list --format=csv > metrics-list.csv
# Once generated, the metrics-list.csv was manually modified to change the case of the headers to lowercase to work with liquid comparison code.
- child_metric_id: changefeed.error_retries
feature: changefeed
- child_metric_id: changefeed.emitted_messages
feature: changefeed
- child_metric_id: changefeed.emitted_batch_sizes
feature: changefeed
- child_metric_id: changefeed.filtered_messages
feature: changefeed
- child_metric_id: changefeed.message_size_hist
feature: changefeed
- child_metric_id: changefeed.emitted_bytes
feature: changefeed
- child_metric_id: changefeed.flushed_bytes
feature: changefeed
- child_metric_id: changefeed.flushes
feature: changefeed
- child_metric_id: changefeed.size_based_flushes
feature: changefeed
- child_metric_id: changefeed.parallel_io_queue_nanos
feature: changefeed
- child_metric_id: changefeed.parallel_io_pending_rows
feature: changefeed
- child_metric_id: changefeed.parallel_io_result_queue_nanos
feature: changefeed
- child_metric_id: changefeed.parallel_io_in_flight_keys
feature: changefeed
- child_metric_id: changefeed.sink_io_inflight
feature: changefeed
- child_metric_id: changefeed.sink_batch_hist_nanos
feature: changefeed
- child_metric_id: changefeed.flush_hist_nanos
feature: changefeed
- child_metric_id: changefeed.commit_latency
feature: changefeed
- child_metric_id: changefeed.admit_latency
feature: changefeed
- child_metric_id: changefeed.backfill_count
feature: changefeed
- child_metric_id: changefeed.backfill_pending_ranges
feature: changefeed
- child_metric_id: changefeed.running
feature: changefeed
- child_metric_id: changefeed.batch_reduction_count
feature: changefeed
- child_metric_id: changefeed.internal_retry_message_count
feature: changefeed
- child_metric_id: changefeed.schema_registry.retry_count
feature: changefeed
- child_metric_id: changefeed.schema_registry.registrations
feature: changefeed
- child_metric_id: changefeed.aggregator_progress
feature: changefeed
- child_metric_id: changefeed.checkpoint_progress
feature: changefeed
- child_metric_id: changefeed.lagging_ranges
feature: changefeed
- child_metric_id: changefeed.cloudstorage_buffered_bytes
feature: changefeed
- child_metric_id: changefeed.kafka_throttling_hist_nanos
feature: changefeed
- child_metric_id: livebytes
feature: virtual
- child_metric_id: keybytes
feature: virtual
- child_metric_id: valbytes
feature: virtual
- child_metric_id: rangekeybytes
feature: virtual
- child_metric_id: rangevalbytes
feature: virtual
- child_metric_id: totalbytes
feature: virtual
- child_metric_id: intentbytes
feature: virtual
- child_metric_id: lockbytes
feature: virtual
- child_metric_id: livecount
feature: virtual
- child_metric_id: keycount
feature: virtual
- child_metric_id: valcount
feature: virtual
- child_metric_id: rangekeycount
feature: virtual
- child_metric_id: rangevalcount
feature: virtual
- child_metric_id: intentcount
feature: virtual
- child_metric_id: lockcount
feature: virtual
- child_metric_id: intentage
feature: virtual
- child_metric_id: gcbytesage
feature: virtual
- child_metric_id: sysbytes
feature: virtual
- child_metric_id: syscount
feature: virtual
- child_metric_id: abortspanbytes
feature: virtual
- child_metric_id: kv.tenant_rate_limit.num_tenants
feature: virtual
- child_metric_id: kv.tenant_rate_limit.current_blocked
feature: virtual
- child_metric_id: kv.tenant_rate_limit.read_batches_admitted
feature: virtual
- child_metric_id: kv.tenant_rate_limit.write_batches_admitted
feature: virtual
- child_metric_id: kv.tenant_rate_limit.read_requests_admitted
feature: virtual
- child_metric_id: kv.tenant_rate_limit.write_requests_admitted
feature: virtual
- child_metric_id: kv.tenant_rate_limit.read_bytes_admitted
feature: virtual
- child_metric_id: kv.tenant_rate_limit.write_bytes_admitted
feature: virtual
- child_metric_id: security.certificate.expiration.client
feature: secure
type: GAUGE
unit: SECONDS
- child_metric_id: jobs.row_level_ttl.span_total_duration
feature: row-level-ttl
- child_metric_id: jobs.row_level_ttl.select_duration
feature: row-level-ttl
- child_metric_id: jobs.row_level_ttl.delete_duration
feature: row-level-ttl
- child_metric_id: jobs.row_level_ttl.rows_selected
feature: row-level-ttl
- child_metric_id: jobs.row_level_ttl.rows_deleted
feature: row-level-ttl
- child_metric_id: jobs.row_level_ttl.num_active_spans
feature: row-level-ttl
- child_metric_id: jobs.row_level_ttl.total_rows
feature: row-level-ttl
- child_metric_id: jobs.row_level_ttl.total_expired_rows
feature: row-level-ttl
- child_metric_id: rpc.connection.healthy
feature: all
- child_metric_id: rpc.connection.unhealthy
feature: all
- child_metric_id: rpc.connection.inactive
feature: all
- child_metric_id: rpc.connection.healthy_nanos
feature: all
- child_metric_id: rpc.connection.unhealthy_nanos
feature: all
- child_metric_id: rpc.connection.heartbeats
feature: all
- child_metric_id: rpc.connection.failures
feature: all
- child_metric_id: rpc.connection.avg_round_trip_latency
feature: all
- child_metric_id: logical_replication.catchup_ranges_by_label
feature: ldr
- child_metric_id: logical_replication.events_dlqed_by_label
feature: ldr
- child_metric_id: logical_replication.events_ingested_by_label
feature: ldr
- child_metric_id: logical_replication.replicated_time_by_label
feature: ldr
- child_metric_id: logical_replication.scanning_ranges_by_label
feature: ldr
---
## File: src/current/_data/v24.3/metrics/metrics.yml
# metrics.yml is a manually curated file of metrics that are included in the Canned Metrics for Serverless deployment.
# The metrics are in the order of appearance in the configuration file:
# https://github.com/cockroachlabs/managed-service/pull/16129/files
# console/assets/js/pages/clusterDetail/metrics/graphConfigs.tsx
# The data for the metrics was also sourced from
# https://github.com/cockroachlabs/docs/blob/main/src/current/_includes/v23.2/essential-metrics.md
#
# The corresponding metrics-list.csv file was generated using the v23.2.0 binary with the following command:
# cockroach gen metric-list --format=csv > metrics-list.csv
# Once generated, the metrics-list.csv was manually modified to change the case of the headers to lowercase to work with liquid comparison code.
- metric_id: sql.new_conns
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Connections Per Second"
datadog_id_selfhosted: sql.new_conns.count
essential: true
metric_type: SQL
metric_ui_tab: [ Overview, SQL ]
metric_ui_graph: "SQL Connections"
- metric_id: sql.select.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Select"
datadog_id_selfhosted: sql.select.count
datadog_id_dedicated: sql.select.count
essential: true
metric_type: SQL
metric_ui_tab: [ Overview, SQL ]
metric_ui_graph: "SQL Statements"
- metric_id: sql.update.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Update"
datadog_id_selfhosted: sql.update.count
datadog_id_dedicated: sql.update.count
essential: true
metric_type: SQL
metric_ui_tab: [ Overview, SQL ]
metric_ui_graph: "SQL Statements"
- metric_id: sql.insert.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Insert"
datadog_id_selfhosted: sql.insert.count
datadog_id_dedicated: sql.insert.count
essential: true
metric_type: SQL
metric_ui_tab: [ Overview, SQL ]
metric_ui_graph: "SQL Statements"
- metric_id: sql.delete.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Delete"
datadog_id_selfhosted: sql.delete.count
datadog_id_dedicated: sql.delete.count
essential: true
metric_type: SQL
metric_ui_tab: [ Overview, SQL ]
metric_ui_graph: "SQL Statements"
- metric_id: sql.service.latency
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "P90, P99, P99.9, P99.99"
datadog_id_selfhosted: sql.service.latency
datadog_id_dedicated: sql.service.latency
essential: true
metric_type: SQL
metric_ui_tab: [ Overview, SQL ]
metric_ui_graph: "Service Latency: SQL Statements"
- metric_id: tenant.consumption.request_units
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "RU, Average RUs"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ Overview, "Request Units"]
metric_ui_graph: "Request Units"
- metric_id: livebytes
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Storage usage"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: Storage
metric_ui_tab: [ Overview ]
metric_ui_graph: Storage
- metric_id: tenant.consumption.sql_pods_cpu_seconds
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Total amount of CPU used by SQL pods"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ "Request Units" ]
metric_ui_graph: "CPU"
- metric_id: tenant.consumption.pgwire_egress_bytes
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Client traffic"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ "Request Units" ]
metric_ui_graph: "Egress"
- metric_id: tenant.consumption.external_io_egress_bytes
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Bulk I/O operations"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ "Request Units" ]
metric_ui_graph: "Egress"
- metric_id: tenant.consumption.read_requests
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Requests"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ "Request Units" ]
metric_ui_graph: "Reads"
- metric_id: tenant.consumption.read_batches
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Batches"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ "Request Units" ]
metric_ui_graph: "Reads"
- metric_id: tenant.consumption.read_bytes
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Bytes"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ "Request Units" ]
metric_ui_graph: "Reads"
- metric_id: tenant.consumption.write_requests
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Requests"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ "Request Units" ]
metric_ui_graph: "Writes"
- metric_id: tenant.consumption.write_batches
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Batches"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ "Request Units" ]
metric_ui_graph: "Writes"
- metric_id: tenant.consumption.write_bytes
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Bytes"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ "Request Units" ]
metric_ui_graph: "Writes"
- metric_id: tenant.consumption.cross_region_network_ru
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Network traffic"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Request Units"
metric_ui_tab: [ "Request Units" ]
metric_ui_graph: "Cross-region Networking"
- metric_id: sql.conn.latency
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "P90, P99"
datadog_id_selfhosted: sql.conn.latency
datadog_id_dedicated: sql.conn.latency
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Connection Latency"
- metric_id: sql.conns
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Connections"
datadog_id_selfhosted: sql.conns
datadog_id_dedicated: sql.conns
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Open SQL Sessions"
- metric_id: sql.txns.open
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Open Transactions"
datadog_id_selfhosted: sql.txns.open
datadog_id_dedicated: sql.txns.open
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Open SQL Transactions"
- metric_id: sql.txn.begin.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Begin"
datadog_id_selfhosted: sql.txn.begin.count
datadog_id_dedicated: sql.txn.begin.count
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transactions"
- metric_id: sql.txn.commit.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Commits"
datadog_id_selfhosted: sql.txn.commit.count
datadog_id_dedicated: sql.txn.commit.count
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transactions"
- metric_id: sql.txn.rollback.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Rollbacks"
datadog_id_selfhosted: sql.txn.rollback.count
datadog_id_dedicated: sql.txn.rollback.count
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transactions"
- metric_id: sql.txn.abort.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Aborts"
datadog_id_selfhosted: sql.txn.abort.count
datadog_id_dedicated: sql.txn.abort.count
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transactions"
- metric_id: txn.restarts.writetooold
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Write Too Old"
datadog_id_selfhosted: txn.restarts.writetooold
datadog_id_dedicated: txn.restarts.writetooold
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transaction Restarts"
- metric_id: txn.restarts.writetoooldmulti
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Write Too Old (multiple)"
datadog_id_selfhosted: txn.restarts.writetoooldmulti.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transaction Restarts"
- metric_id: txn.restarts.serializable
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Forwarded Timestamp"
datadog_id_selfhosted: txn.restarts.serializable
datadog_id_dedicated: txn.restarts.serializable
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transaction Restarts"
- metric_id: txn.restarts.asyncwritefailure
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Async Consensus Failure"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transaction Restarts"
- metric_id: txn.restarts.readwithinuncertainty
deploy_selfhosted: false
deploy_dedicated: false
deploy_standard: true
short_name: "Read Within Uncertainty Interval"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transaction Restarts"
- metric_id: txn.restarts.txnaborted
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Aborted"
datadog_id_selfhosted: txn.restarts.txnaborted.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transaction Restarts"
- metric_id: txn.restarts.txnpush
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Push Failure"
datadog_id_selfhosted: txn.restarts.txnpush.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transaction Restarts"
- metric_id: txn.restarts.unknown
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Unknown"
datadog_id_selfhosted: txn.restarts.unknown.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transaction Restarts"
- metric_id: sql.txn.latency
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "P90, P99"
datadog_id_selfhosted: sql.txn.latency
datadog_id_dedicated: sql.txn.latency
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Transaction Latency"
- metric_id: sql.statements.active
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Active Statements"
datadog_id_selfhosted: sql.statements.active
datadog_id_dedicated: sql.statements.active
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Active SQL Statements"
- metric_id: sql.failure.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Errors"
datadog_id_selfhosted: sql.failure
datadog_id_dedicated: sql.failure.count
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "SQL Statement Errors"
- metric_id: sql.distsql.contended_queries.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Contention"
datadog_id_selfhosted: sql.distsql.contended.queries
datadog_id_dedicated: sql.distsql.contended.queries
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "SQL Statement Contention"
- metric_id: sql.full.scan.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Full scans"
datadog_id_selfhosted: sql.full.scan
datadog_id_dedicated: sql.full.scan.count
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Full Scans"
- metric_id: sql.ddl.count
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "DDL Statements"
datadog_id_selfhosted: sql.ddl.count
datadog_id_dedicated: sql.ddl.count
essential: true
metric_type: SQL
metric_ui_tab: [ SQL ]
metric_ui_graph: "Schema Changes"
- metric_id: jobs.auto_create_stats.currently_running
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Auto Create Statistics Running"
datadog_id_selfhosted: jobs.auto_create_stats.currently_running
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Table Statistics"
metric_ui_tab: [ SQL, Custom ]
metric_ui_graph: "Statistics Jobs"
- metric_id: jobs.create_stats.currently_running
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Create Statistics Running"
datadog_id_selfhosted: jobs.create_stats.currently_running
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Table Statistics"
metric_ui_tab: [ SQL, Custom ]
metric_ui_graph: "Statistics Jobs"
- metric_id: jobs.auto_create_stats.resume_failed
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Auto Create Statistics Failed"
datadog_id_selfhosted: jobs.auto.create.stats.resume_failed.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Table Statistics"
metric_ui_tab: [ SQL, Custom ]
metric_ui_graph: "Statistics Jobs"
- metric_id: jobs.auto_create_stats.currently_paused
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Auto Create Statistics Paused"
datadog_id_selfhosted: jobs.auto.create.stats.currently_paused
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Table Statistics"
metric_ui_tab: [ SQL, Custom ]
metric_ui_graph: "Statistics Jobs"
- metric_id: changefeed.running
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Running"
datadog_id_selfhosted: changefeed.running
datadog_id_dedicated: changefeed.running
essential: true
metric_type: Changefeeds
metric_ui_tab: [ Changefeeds, Custom ]
metric_ui_graph: "Changefeed Status"
- metric_id: jobs.changefeed.currently_paused
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Paused"
datadog_id_selfhosted: jobs.changefeed.currently_paused
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: Changefeeds
metric_ui_tab: [ Changefeeds, Custom ]
metric_ui_graph: "Changefeed Status"
- metric_id: changefeed.failures
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Failures"
datadog_id_selfhosted: changefeed.failures
datadog_id_dedicated: changefeed.failures
essential: true
metric_type: Changefeeds
metric_ui_tab: [ Changefeeds, Custom ]
metric_ui_graph: "Changefeed Status"
- metric_id: changefeed.error_retries
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Errors"
datadog_id_selfhosted: changefeed.error_retries
datadog_id_dedicated: changefeed.error_retries
essential: true
metric_type: Changefeeds
metric_ui_tab: [ Changefeeds, Custom ]
metric_ui_graph: "Retryable Errors"
- metric_id: changefeed.emitted_messages
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Emitted messages"
datadog_id_selfhosted: changefeed.emitted.messages
datadog_id_dedicated: changefeed.emitted.messages
essential: true
metric_type: Changefeeds
metric_ui_tab: [ Changefeeds, Custom ]
metric_ui_graph: "Emitted Messages"
- metric_id: changefeed.emitted_bytes
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Emitted bytes"
datadog_id_selfhosted: changefeed.emitted_bytes.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: Changefeeds
metric_ui_tab: [ Changefeeds, Custom ]
metric_ui_graph: "Emitted Bytes"
- metric_id: changefeed.commit_latency
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "P99, P90"
datadog_id_selfhosted: changefeed.commit_latency
datadog_id_dedicated: changefeed.commit_latency
essential: true
metric_type: Changefeeds
metric_ui_tab: [ Changefeeds, Custom ]
metric_ui_graph: "Commit Latency"
- metric_id: jobs.changefeed.protected_age_sec
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Protected Timestamp Age"
datadog_id_selfhosted: jobs.changefeed.protected_age_sec
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: Changefeeds
metric_ui_tab: [ Changefeeds, Custom ]
metric_ui_graph: "Oldest Protected Timestamp"
- metric_id: jobs.row_level_ttl.resume_completed
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Resume Completed"
datadog_id_selfhosted: jobs.row_level_ttl.resume_completed.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL", Custom ]
metric_ui_graph: "Row-Level TTL Jobs"
- metric_id: jobs.row_level_ttl.currently_running
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Running"
datadog_id_selfhosted: jobs.row.level.ttl.currently_running
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL", Custom ]
metric_ui_graph: "Row-Level TTL Jobs"
- metric_id: jobs.row_level_ttl.currently_paused
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Paused"
datadog_id_selfhosted: jobs.row_level_ttl.currently_paused
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL", Custom ]
metric_ui_graph: "Row-Level TTL Jobs"
- metric_id: jobs.row_level_ttl.resume_failed
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Resume Failed"
datadog_id_selfhosted: jobs.row_level_ttl.resume_failed.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL", Custom ]
metric_ui_graph: "Row-Level TTL Jobs"
- metric_id: schedules.scheduled-row-level-ttl-executor.failed
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Failed Schedules"
datadog_id_selfhosted: schedules.scheduled-row-level-ttl-executor.failed.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL", Custom ]
metric_ui_graph: "Row-Level TTL Jobs"
- metric_id: jobs.row_level_ttl.rows_selected
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Rows selected"
datadog_id_selfhosted: jobs.row_level_ttl.rows_selected.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL", Custom ]
metric_ui_graph: "Processing Rate"
- metric_id: jobs.row_level_ttl.rows_deleted
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Rows deleted"
datadog_id_selfhosted: jobs.row_level_ttl.rows_deleted.count
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL", Custom ]
metric_ui_graph: "Processing Rate"
- metric_id: jobs.row_level_ttl.total_rows
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Total Rows"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL" ]
metric_ui_graph: "Estimated Rows"
- metric_id: jobs.row_level_ttl.total_expired_rows
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Expired Rows"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL" ]
metric_ui_graph: "Estimated Rows"
- metric_id: jobs.row_level_ttl.select_duration
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Select Latency (P90), Select Latency (P99)"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL" ]
metric_ui_graph: "Row-Level TTL Job Latency"
- metric_id: jobs.row_level_ttl.delete_duration
deploy_selfhosted: true
deploy_dedicated: true
deploy_standard: true
short_name: "Delete Latency (P90), Delete Latency (P99)"
datadog_id_selfhosted: "NOT AVAILABLE"
datadog_id_dedicated: "NOT AVAILABLE"
essential: true
metric_type: "Row-Level TTL"
metric_ui_tab: [ "Row-Level TTL" ]
metric_ui_graph: "Row-Level TTL Job Latency"