Get started with a Key-Value instance

OceanBase Cloud provides transactional instances, analytical instances, and Key-Value instances. This topic guides you through a quick experience of Key-Value instances.

Overview

Key-Value instance (OBKV for short) is a series of NoSQL products built on top of OceanBase distributed storage engine. Key-Value instance has two models: OBKV-Table and OBKV-HBase. It inherits OceanBase's fundamental capabilities of high performance, transactions, distribution, multi-tenancy, and high reliability. OBKV helps enterprises unify their technology stack, meeting business requirements for multi-model NoSQL databases while reducing the complexity of database operations and maintenance.

OBKV-Table

OBKV-Table provides capabilities such as table-based massive data read/write, global and local secondary indexes, filtering query, and time-to-live (TTL). This model applies to a massive data read/write scenario that does not involve complex queries but demands extremely high query performance.

For more information about OBKV-Table, see Overview.

OBKV-HBase

OBKV-HBase provides wide table services compatible with HBase APIs. It can achieve data read performance several times higher than that of open source HBase at much lower costs. For more information, see Application scenarios.

For more information about OBKV-HBase, see Overview.

Step 1: Create an OceanBase Cloud account

1. Navigate to the OceanBase official website, and click Get Started to redirect to the OceanBase Cloud console.

   

2. Click Sign Up.

3. On the Sign Up page, provide the necessary information for the registration, including your email, the verification code you receive via email, password, and your country.

4. Check the box of I agree to OceanBase International Privacy Policy and click Sign Up to create an account.

Step 2: Create a Key-Value instance

1. Log in to the OceanBase Cloud console with the account you just created.

2. Click Create Instance displayed on the page.

3. On the Create Instance page, select Dedicated (Key-Value) under Instance Type.

4. Select your cloud vendor and the deployment region. OceanBase Cloud supports AWS as the cloud provider.

5. Select your instance specifications.

   Parameter	Description
   Instance Name	Set the instance name. The name must be 2 to 64 characters in length and can contain only Chinese characters, digits, uppercase and lowercase letters, underscores, and hyphens.
   Storage Architecture	Unified Storage & Compute: The computing resources and data storage are in the same node. Data is locally processed on the computing node. Separated Storage & Compute: This cloud-native architecture separates storage and computing in an instance by using multiple computing nodes and shared storage technology. For more information, see Storage architecture.
   Version	The OceanBase database version.
   Deployment Mode	Single-IDC Deployment: All nodes are located within the same zone. This deployment supports one-node, two-node, and three-node configurations within a single IDC. If you require this setup, please contact OceanBase technical support. Dual-IDC Deployment: Two nodes are deployed across two zones, with a third node deployed in a different zone solely for log synchronization. Multi-IDC Deployment: Primary and standby nodes are located in different zones, enabling disaster recovery across zones. This deployment comes at no additional cost and by default, all three zones are selected. For more information, see Deployment modes.
   Zone	Select the target zone. You can select the zone with the lowest network latency by using View Network Latency. Single-IDC deployment: Select one zone. Dual-IDC deployment: Select two zones. Multi-IDC deployment: Select three zones.
   Compute	Select the compute specification as needed.
   Storage	The storage specifications vary by compute specifications. Select the storage specification as needed. For more information, see Instance billing.

6. Specify the number of instances you want to create in the Quantity section.

7. In the Summary section on the right, confirm the configurations and then click Create Instance.

   After the creation is completed, you can navigate back to the Instances page to view the creation progress.

Step 3: Create a tenant

1. Log in to the OceanBase Cloud console with the account you just created.

2. Click Instances displayed in the left navigation pane.

3. On the Instances page, after the instance is created, click the name of the instance to go to the Overview page of the instance.

4. In the upper-right corner of the Overview page, click Create Tenant.

5. Complete the configurations for your tenant based on your needs.

   Field	Description
   Tenant Name	The name of the tenant. The tenant name must start with a letter or an underscore (_), and contain 2 to 20 characters, which can be uppercase letters, lowercase letters, digits, and underscores. It cannot be set to sys.
   Compatibility Mode	The mode of the tenant. Valid values: OBKV-HBase Compatible and OBKV-Table Compatible.
   Number of Resource Units	OceanBase Database manages physical resources based on resource units. A resource unit is a collection of physical resources such as CPU, memory, disk space, and IOPS. Each resource unit contains three nodes. Three nodes are added each time you add a resource unit.
   Unit Specification	The CPU and memory capacities on a single node of the tenant. Note The total CPU and memory capacities of all tenants cannot exceed the specifications of the cluster to which they belong. Total available resources of a tenant = Resources on a single node × Number of resource distribution nodes × Number of replicas
   Character Set	The character set of the tenant. OBKV Supports utf8mb4 character set.
   Time Zone	The time zone of the tenant.
   Primary Zone	The primary zone of the tenant.
   Network Settings	When selected, a public endpoint will be created automatically.
   Remarks (Optional)	Additional information about the tenant. The remarks cannot exceed 30 characters in length.

6. Click Create. You can view the progress of tenant creation on the Instances page.

Step 4: Create an account

1. Log in to the OceanBase Cloud console.

2. In the left-side navigation pane, click Instances.

3. In the instance list, click the name of the target cluster instance to go to the Overview page of the instance.

4. In the left-side navigation pane, click Tenants.

5. In the tenant list, click the More icon in the line of the target tenant and select Create Account.

6. Configure the following parameters.

   

   Parameter	Description
   Account Name	The name of the account. The account name must start with a lowercase letter and be 2 to 32 characters in length. It can contain uppercase letters, lowercase letters, hyphens (-), underscores (_), and digits, and cannot contain reserved keywords (case-insensitive), such as SYS, OCEANBASE, ROOT, OPERATOR, LBACSYS, ORAAUDITOR, OBMIGRATE, OMC, IDB_DDL, ODC_RND, ODC_DDL, and DWEXP.
   Account Type	The type of the account. Valid values for MySQL-compatible tenants: Regular Account, Super Account, and Read-only Account. Valid values for Oracle-compatible tenants: Regular Account and Super Account. A regular account has the privileges to execute DML and DDL statements in the database. For more information, refer to Account privileges. By default, the super account has read/write privileges on all databases. By default, a read-only account has the read privilege on all databases. Note DML statements access and manipulate data in existing schema objects. DDL statements create, alter, and drop schema objects. For more information, refer to SQL statement overview.
   Grant Database Privileges	This parameter is displayed only when you create a regular account in a MySQL-compatible tenant. You can grant privileges of the following types to an unauthorized account: Custom, readonly, readwrite, DDL, and DML. You can grant the following database privileges to an account in the MySQL compatible mode: Custom: ALTER, CREATE, DELETE, DROP, INSERT, SELECT, UPDATE, INDEX, CREATE VIEW, and SHOW VIEW. You can select multiple privileges. readonly: CREATE SESSION, SELECT, and SHOW VIEW. readwrite: all privileges except GRANT OPTION. DDL: CREATE, DROP, ALTER, SHOW VIEW, and CREATE VIEW. DML: SELECT, INSERT, UPDATE, DELETE, SHOW VIEW, and PROCESS.
   Password	The password of the account. The password must be 8 to 32 characters in length and contain at least two uppercase letters, two lowercase letters, two digits, and two special characters. Supported special characters are ~!@#%^&*_-+=\|(){}[]:;,.?/".
   Randomly generate	If you click this button, the system automatically generates a password. You need to copy and keep the password confidential.
   Remarks (Optional)	Additional information about the account. The remarks cannot exceed 30 characters in length.

7. Click Create.

Step 5: Connect to a Key-Value instance

1. Log in to the OceanBase Cloud console, and in the left-side navigation pane, click Instances.

2. On the Instances page, expand the the target cluster instance and click Connect > Get Connection String under the target tenant.

3. In the dialog box that appears, click Connect via Public Network.

4. Under Step 1: Get Public Endpoint, click Get Public Endpoint.

5. Once the public endpoint is generated, complete the following configurations under Step 2: Security Settings, then, click Next Step.

   1. Add an IP address: Click Add to add your outbound IP to the allowlist.

      • Add My Current IP Address: Your current IP address is automatically obtained and entered. Other IP addresses must be manually entered.

      • Allow Access from Anywhere: 0.0.0.0 is automatically entered. In this case, all IP addresses can be used to access the current cluster instance.

   2. Download the CA certificate: Download the certificate and complete the configuration. For more information, refer to SSL link encryption.

6. Under Step 3: Connect, create a database and an account.

   1. Create a database: Click + Create Database. In the dialog box that appears, specify a name for the database, such as default_database. Then, click Create.

   2. Create an account: Click + Create Account. In the dialog box that appears, specify an account name and click Generate Password. Then, the system will automatically generate a password for your account. You can also define a password. The password must be 10 to 32 characters in length and contain at least two digits, two uppercase letters, two lowercase letters, and two special characters. Supported special characters are @ # $ % _ +.

      Notice

      Please save the password generated in a secure place when the account is created.

7. Select MySQL CLI and copy the generated connection string to your client.

   Currently, OceanBase Cloud supports a wide range of clients, drivers, and languages.

8. In the CLI of your MySQL client, enter the account name and password generated in Step 6. Then, you can connect to and use OceanBase Cloud.

Step 6: Try Key-Value instance

1. Connect to your Key-Value instance.

2. Use this statement to create a table named htable1$family.

   CREATE TABLEGROUP htable1;
   
   CREATE TABLE htable1$family (
       K varbinary(1024),
       Q varbinary(256),
       T bigint,
       V varbinary(1048576) NOT NULL,
       PRIMARY KEY(K, Q, T)) 
       TABLEGROUP =  htable1 ;
   

3. Insert data by using Put.

   // Insert one row
   String key = "testKey0";
   String family = "family";
   String column = "column";
   String value = "putValue";
   Put put = new Put(key.getBytes());
   put.add(family.getBytes(), column.getBytes(), value.getBytes());
   hTable.put(put);
   
   // Insert multiple rows
   Put put1 = new Put(Bytes.toBytes("testKey1"));
   put1.add(toBytes(family), toBytes(column), toBytes(value));
   //put1.add(toBytes(family), toBytes(column), System.currentTimeMillis(), toBytes(value));
   
   Put put2 = new Put(Bytes.toBytes("testKey2"));
   put2.add(toBytes(family), toBytes(column), toBytes(value));
   //put2.add(toBytes(family), toBytes(column), System.currentTimeMillis(), toBytes(value));
   List<Put> puts = new ArrayList<Put>();
   puts.add(put1);
   puts.add(put2);
   hTable.put(puts);
   

   In the preceding example, three cells are inserted into the database.

4. Qeury the inserted data.

   MySQL [test]> SELECT * FROM htable1$family;
   +----------+--------+----------------+----------+
   | K        | Q      | T              | V        |
   +----------+--------+----------------+----------+
   | testKey0 | column | -1715961035391 | putValue |
   | testKey1 | column | -1715961035471 | putValue |
   | testKey2 | column | -1715961035471 | putValue |
   +----------+--------+----------------+----------+