What’s New and Improved in YugabyteDB Docs

Welcome to our first blog post focused on what’s new and improved in YugabyteDB Docs. We’re continually adding to and updating the documentation to give you the information you need to make the most out of YugabyteDB. This post covers recent content added, and changes made, to the YugabyteDB documentation. Before jumping into new content, the first section covers the efforts we’ve made to help you quickly find the answers you’re looking for.

Find answers

During the past few months, we’ve made many behind-the-scenes changes to make it easier and faster for you to find what you’re looking for, whether you’re using Google or our own search functionality.

Google Search

• “Only the latest”: Now, when you use Google Search to find answers in the YugabyteDB documentation, you should only see results from the latest version.
• Descriptive titles and summaries: When YugabyteDB Docs content shows up in your Google Search queries, results from our documentation pages now include more descriptive titles and summaries of what to expect on the linked pages.

YugabyteDB Docs Search

At the top of every page in YugabyteDB Docs, you can enter search terms into the “Search YugabyteDB Docs” field and use our internal search engine to find answers. Here are some recent enhancements we’ve made to the internal search functionality:

• Search results for the “latest” YugabyteDB version are returned by default.
  • Note: For earlier versions, select your version in the drop-down on the navigation bar and search results are only returned for that version’s content.
• When searching for specific commands and flags, underscores are not ignored.
  • Example: A search for “list_tablets” only returns results that include that exact command, rather than lots of false positives.
• Use quotes to restrict your search results to specific phrases.
  • Examples: “SPLIT INTO”, “CREATE TABLE”

New and improved documentation

Included below are new and improved pages in the Yugabyte Docs.

YugabyteDB Architecture

DocDB is YugabyteDB’s distributed document store that is responsible for transactions, sharding, replication, and persistence. To help you better understand DocDB and each of its layers, the following topics in the Architecture documentation have been reorganized. We have given clearer titles, and have added new content about transactions, hybrid logical clocks, concurrency control, and explicit row-locking.

DocDB transactions layer

• Transactions overview
  Describes support for distributed ACID transactions, time synchronization using hybrid logical clocks (HLCs), data consistency using MVCC, explicit locking, and single-row transactions (for INSERT, UPDATE, and DELETE).

• Transaction isolation levels
  Highlights how SERIALIZABLE and SNAPSHOT isolation levels work in YugabyteDB. Note that YSQL supports both these isolation levels with SNAPSHOT (aka REPEATABLE READ) as default while YCQL supports only SNAPSHOT isolation.

• Explicit locking
  Describes concurrency control including optimistic and pessimistic (with deadlock detection) locking. Support for row-level locks: FOR UPDATE, FOR NO KEY UPDATE, FOR SHARE, and FOR KEY SHARE.

• Single-row ACID transactions
  For single rows or multiple rows within the same shard (tablet), YugabyteDB reads the latest data from a recently elected leader, uses leader leases to read the latest data in case of a network partition, assigns a safe timestamp for a read request, and propagates safe time from leader to followers for follower-side reads.

• Distributed ACID transactions
  For multiple rows across multiple shards, provide strongly consistent secondary indexes and multi-table/row ACID operations by using provisional records and transaction status tracking.

• Transactional IO path
  Follow the steps in the write path of a transaction modifying multiple keys and the steps in the read path for requests of a consistent combination of values from multiple tables.

DocDB sharding layer

• Hash and range sharding
  Evenly and randomly distribute data across shards or split rows of contiguous ranges respecting table sort order based on primary key column values.

• Tablet splitting
  Change the number of tablets, at run-time, for range scans, low-cardinality primary keys, and rebalancing oversized “small” tables.

• Colocated tables
  Accommodate relational tables and workloads by gathering all data into a colocation tablet to increase the number of relations (tables, indexes, and more) per node, while keeping the number of tablets per node low.

DocDB replication layer

• Replication
  Replicate data synchronously inside a cluster using the Raft consensus algorithm.

• xCluster replication
  Enable asynchronous replication across clusters.

• Read replicas
  DocDB extends Raft to add read replica clusters powered by asynchronous replication from the primary cluster.

• Change data capture (CDC)
  Use CDC to ensure incremental data changes are identified and asynchronously replicated to remote systems.

DocDB storage layer

• Persistence
  The storage model uses DocDB key and DocDB values and allows multiple levels of nesting. Hybrid timestamps for each update. Mapping SQL rows to DocDB: for YSQL and YCQL tables, every row is a document. Data expiration (TTL) in YCQL and an example.

• Performance
  DocDB enhanced RocksDB for better scalability and performance. Data model aware Bloom filters. Range query optimizations. Efficient memory usage. Scan-resistant block cache.

YugabyteDB APIs

YugabyteDB provides two distributed SQL APIs.

• Yugabyte Structured Query Language (YSQL) is a PostgreSQL-compatible fully-relational API.
• Yugabyte Cloud Query Language (YCQL) is a semi-relational API with document data modeling and has its roots in the Apache Cassandra Query Language.

Here’s what’s new for these APIs.

YSQL

• Array data types and functionality
  This section details array data types, literals, and detailed explanations and examples for 14 array functions and operators. More than just providing syntax, these topics provide insights into the nuances of working with array data types.

• Benchmark YSQL performance using sysbench
  Sysbench is a popular database benchmarking tool for databases, like PostgreSQL and MySQL. This page includes steps to run your own benchmark tests of YSQL with a forked version of sysbench, modified to better represent YugabyteDB’s distributed SQL capabilities.

• Install and use extensions
  This updated page includes lists of bundled extensions and extensions requiring installation. It also includes steps on adding the PostgreSQL HyperLogLog (postgresql-hll) extension to YugabyteDB, letting you scale your use of SELECT COUNT(DISTINCT) without sacrificing speed and memory.

• CREATE EXTENSION / DROP EXTENSION
  These new topics cover the syntax and semantics of these two YSQL statements, used for loading and removing extensions in YugabyteDB.

YCQL

• Best practices
  Learn the developer best practices for using YugabyteDB core features and optimizing performance with YCQL.

• cqlsh changed to ycqlsh
  The YCQL shell binary has been renamed to ycqlsh (previously cqlsh). All of the documentation and examples have been updated to use this more appropriate name. This change also helps you when searching on Google Search or when using our internal documentation search.

Deploy YugabyteDB on Kubernetes

The Deployment user guide covers topics related to deploying YugabyteDB on any public cloud or private data center including Kubernetes environments. Here’s what’s new:

• Client connectivity to Kubernetes clusters
  This new topic describes the different options you have for connecting to YugabyteDB on clusters deployed within Kubernetes. Steps are included for how to connect from within a Kubernetes cluster or externally.

• Use Helm chart to deploy on Azure Kubernetes Service (AKS)
  In this new page, follow the steps to use the Helm chart to deploy a single-zone YugabyteDB cluster on Azure Kubernetes Service.

Manage YugabyteDB at scale with Yugabyte Platform

Use the Yugabyte Platform to build your own DB-as-a-Service. Its built-in orchestration and monitoring capabilities make it easy to create and manage multiple YugabyteDB clusters in private/public clouds and Kubernetes environments.

• Back up and restore Yugabyte Platform
  Follow the steps in this topic to back up your Yugabyte Platform installation and restore it, if needed, for disaster recovery or moving to a new server.

• Schedule a data backup
  Learn how to create regularly scheduled backups of data on your YugabyteDB universes or just selected tables. Also included here are steps to disable or remove scheduled backups.

What’s new in release notes

In an effort to help you understand the relevance of features, enhancements, and resolved issues, along with relevant contextual information and links to documentation that more fully explain features and enhancements. To see an example of this new approach, take a look at a recent What’s new page.

What’s next?

To help you learn and use YugabyteDB effectively and to get you the answers you need, Yugabyte constantly updates and adds new topics to the YugabyteDB documentation. Here are a few ways you can contribute:

• File GitHub issues for the docs. If you discover missing information, incorrect information, unclear explanations, or have new topics you’d like to see, click New issue and add the “area/documentation” label.
• Contribute to the YugabyteDB docs. Share your knowledge and lessons learned with the Yugabyte by contributing to the YugabyteDB Docs. You will get recognition and rewards for your efforts as part of our recently launched Community Heroes program.
• Ask questions and share answers in our Slack community. Your questions in the yugabyte-db Slack community are seen by fellow members and contributors who are there to help you move forward. Additionally, we routinely create new documentation pages based on topics that are of interest to users on the community Slack.