Connect to a database using a Go client: Examples
This topic describes how to use the Go client and its interfaces.
Connect to an OceanBase database
Use the Go client to log on to OceanBase. For more information, see Connect to an OceanBase database using a Go client.
Run the CREATE TABLE statement to create a table.
CREATE TABLE IF NOT EXISTS `test_varchar_table_00` (
`c1` varchar(20) NOT NULL,
`c2` varchar(20) DEFAULT NULL,
`c3` varchar(20) DEFAULT NULL,
PRIMARY KEY (`c1`)
);
The insert interface
Use this interface to insert a record. If a record with the same primary key already exists, the insertion fails.
Example:
long insert(String tableName, Object rowkey, String[] columns, Object[] values);
long insert(String tableName, Object[] rowkeys, String[] columns, Object[] values);
// Example. The rowkey corresponds to the primary key of the table.
client.insert( "testHash",
new Object[] { 1L, "partition".getBytes(), timeStamp },
new String[] { "V" },
new Object[] { "value".getBytes() }
);
Parameter descriptions:
tableName: The table name.
rowkey: The primary key value.
columns: The names of one or more columns to insert.
values: The values for the columns to insert.
long: The return value, which is the number of inserted rows. A successful insertion returns 1.
The get interface
Use this interface to retrieve a record. If the record exists, the interface returns the record. Otherwise, it returns an empty value.
Example:
Map<String, Object> get(String tableName, Object rowkey, String[] columns);
Map<String, Object> get(String tableName, Object[] rowkeys, String[] columns);
// The rowkey is the primary key.
Map<String, Object> res = client.get("testHash",
new Object[] { 1L, "partition".getBytes(), timestamp },
new String[] { "K", "Q", "T","V" }
);
// The returned value is an object. Cast it directly. For example: Long k = (Long) res.get("K");
Parameter descriptions:
tableName: The table name.
rowkey: The primary key value.
columns: The names of one or more columns to retrieve.
Map<String, Object>: The return value. If the operation is successful, the interface returns the result for the selected columns. If the record is not found, it returns an empty value.
The delete interface
Use this interface to delete a record. If the record does not exist, the number of affected rows is 0. If the record is deleted, the number of affected rows is 1.
Example:
long delete(String tableName, Object rowkey);
long delete(String tableName, Object[] rowkeys);
// Example. The rowkey corresponds to the primary key of the table.
client.delete("testHash", new Object[] { 1L, "partition".getBytes(), timeStamp });
// The result indicates the number of affected rows (affectrows). In this case, 1L is returned.
Parameter descriptions:
tableName: The table name.
rowkey: The primary key of the record to delete.
long: The return value, which is the number of deleted rows. A successful deletion returns 1.
The update interface
Use this interface to update a record. If the target record does not exist, the number of affected rows is 0. If the record is updated, the number of affected rows is 1.
Example:
long update(String tableName, Object rowkey, String[] columns, Object[] values);
long update(String tableName, Object[] rowkeys, String[] columns, Object[] values);
// Example. The rowkey is the primary key of the table.
client.update("testHash",
new Object[] { 1L, "partition".getBytes(), timeStamp },
new String[] { "V" },
new Object[] { "value1L".getBytes() }
);
// The result indicates the number of affected rows (affectrows). In this case, 1L is returned.
Parameter descriptions:
tableName: The table name.
rowkey: The primary key of the record to update.
columns: One or more target columns to update.
values: The new values for one or more columns.
long: The return value, which is the number of updated rows. A successful update returns 1.
The replace interface
Use this interface to replace a record. This operation has three possible outcomes:
If the target record does not exist, the interface inserts the record.
If a record with the same primary key already exists, the interface deletes the original record and then inserts the new record.
If a unique index conflict occurs, the interface deletes all conflicting records and then inserts the new record.
Example:
long replace(String tableName, Object rowkey, String[] columns, Object[] values);
long replace(String tableName, Object[] rowkeys, String[] columns, Object[] values);
// Example. The rowkey is the primary key of the table.
client.replace("testHash",
new Object[] { 1L, "partition".getBytes(), timeStamp },
new String[] { "V" },
new Object[] { "value1L".getBytes() }
);
// The result indicates the number of affected rows (affectrows). In this case, 1L is returned.
Parameter descriptions:
tableName: The table name.
rowkey: The primary key.
columns: The names of one or more target columns to replace.
values: The new values for one or more target columns.
long: The return value, which is the number of replaced rows. A successful replacement returns 1.
The insertOrUpdate interface
Use this interface to insert or update a record. This operation has three possible outcomes:
If the target record does not exist, the interface inserts the record.
If a record with the same primary key already exists, the interface updates the record.
If a unique index conflict occurs during insertion, the interface performs an update operation instead.
Example:
long insertOrUpdate(String tableName, Object rowkey, String[] columns, Object[] values);
long insertOrUpdate(String tableName, Object[] rowkeys, String[] columns, Object[] values);
// Example. The rowkey is the primary key of the table.
client.insertOrUpdate("testHash",
new Object[] { 1L, "partition".getBytes(), timestamp },
new String[] { "V" },
new Object[] { "bb".getBytes() }
);
// The result indicates the number of affected rows (affectrows). In this case, 1L is returned.
Parameter descriptions:
tableName: The table name.
rowkey: The primary key.
columns: The names of one or more target columns for the operation.
values: The values for one or more target columns.
long: The return value, which is the number of rows inserted or updated. A successful operation returns 1.
The increment interface
Use this interface to atomically change the value of a specified column by a given increment. The increment can be a negative number to perform a decrease. This operation has three possible outcomes:
If the result overflows the value range of the column type, an error is reported.
If the target record does not exist, the interface inserts a new record and sets the increment as the initial value. This is equivalent to an original value of 0.
If the target record exists but the value of the specified column is NULL, the interface sets the increment as the initial value. This is equivalent to an original value of 0.
Example:
Map<String, Object> increment(String tableName, Object rowkey, String[] columns,Object[] values, boolean withResult);
Map<String, Object> increment(String tableName, Object[] rowkeys, String[] columns, Object[] values, boolean withResult);
// Example. The rowkey is the primary key of the table. The default value is null, so the final result is c2=1 and c3=2.
Client.increment("test_increment",
"test_null",
new String[] { "c2", "c3" },
new Object[] { 1, 2 }, true );
Parameter descriptions:
tableName: The table name.
rowkey: The primary key value.
columns: The names of one or more target columns to increment.
values: The increment values for one or more target columns.
withResult: Specifies whether to return the result set after the increment operation.
Map<String, Object>: The return value. If withResult is set to false, the interface returns Map.empty.
The append interface
Use this interface to atomically append a string to the value of a specified column. This operation has three possible outcomes:
If the result overflows the value range of the column type, an error is reported.
If the target record does not exist, the interface inserts a new record and sets the appended string as the initial value. This is equivalent to an original value of an empty string.
If the target record exists but the value of the specified column is NULL, the interface sets the appended string as the initial value. This is equivalent to an original value of an empty string.
Example:
Map<String, Object> append(String tableName, Object rowkey, String[] columns, Object[] values,boolean withResult);
Map<String, Object> append(String tableName, Object[] rowkeys, String[] columns, Object[] values, boolean withResult);
// First, insert a record: c2 = {1}, c3 = {"P"}
client.insert("test_append", "test_normal", new String[] { "c2", "c3" }, new Object[] { new byte[] { 1 }, "P" });
// After the append operation, c2 = {1, 2} and c3 = {"PY"}
Map<String, Object> res = client.append("test_append", "test_normal", new String[] { "c2", "c3" }, new Object[] { new byte[] { 2 }, "Y" }, true);
Parameter descriptions:
tableName: The table name.
rowkey: The primary key value.
columns: The names of one or more target columns to which the string is appended.
values: The string values to append to one or more target columns.
withResult: Specifies whether to return the result set after the append operation.
Map<String, Object>: The return value. If withResult is set to false, the interface returns Map.empty.
The scan interface
Use this interface to perform a range scan. You can perform range scans by primary key or primary key prefix. You can also scan by an index or an index prefix range. The interface supports multi-range and reverse scans.
Example:
// Sample
TableQuery tableQuery = client.query("table_name"); // Create a scan object using the table name.
resultSet = tableQuery.select("column2").primaryIndex().addScanRange("min1", "max1).addScanRange("min2", "max2").setBatchSize(batch_size).execute();
while(resultSet.next()) {
Map<String, Object> value = resultSet.getRow();
}
Parameter descriptions:
tableName: The name of the table to scan.
primaryIndex: Specifies that the scan is based on the primary key value.
columns: The names of the columns from which to retrieve results. For example, if a table has columns named column1 to column4, and you need data only from column2.
addScanRange: Adds a search range. The min and max parameters define the lower and upper boundaries of the range.
batchSize: The number of matching records to return in each batch.
The batch interface
Use this interface to execute a combination of multiple operations in a batch.
Example:
TableBatchOps batchOps = client.batch("test_varchar_table");
batchOps.insert("foo", new String[] { "c2" }, new String[] { "bar" });
batchOps.get("foo", new String[] { "c2" });
batchOps.delete("foo");
List<Object> results = batchOps.execute();
// The returned list contains the results. The insert operation returns affectedRows, the get operation returns a map result, and the delete operation returns affectedRows.
Parameter descriptions:
TableBatchOps: The operation object. This object is created using an ObTableClient object, such as client.batch(tableName) in the example.
List<Object>: The return value. This list contains the result set of each operation in the batch, such as the insert, get, and delete operations in the example.