使用 API 建立單一表格
此表格是保留使用者資料的基本結構。您可以使用 SQL 命令 (CREATE TABLE 陳述式) 或 TableRequest API 命令來建立新表格。
您也可以使用 Oracle NoSQL Cloud Infrastructure (OCI) 主控台或 OCI 命令行介面 (OCI-cli)，在 NDCS 中建立表格。
建立表格的準則：
-
表格定義必須至少包含一個欄位定義，且僅包含一個主索引鍵定義。如需主索引鍵定義的詳細資訊，請參閱建立表格。
-
欄位定義會指定資料欄的名稱、其資料類型、資料欄是否可為空值、選擇性預設值 (無論資料欄是否為 IDENTITY 資料欄和選擇性註解)。依預設，所有欄位 (PRIMARY KEY 除外) 都可為空值。
-
主索引鍵設定 (key_definition) 的語法會將表格的主索引鍵資料欄指定為欄位名稱的順序清單。
-
使用存留時間 (TTL) 值來計算資料列的到期時間。到期的資料列不會包含在查詢結果中，最終會由 Oracle NoSQL Database 自動從表格中移除。如果您在建立表格時指定 TTL 值，則會對插入此表格的每個資料列套用作為預設 TTL。
建立一個表格：
使用 SQL 命令
您可以在 SQL 中使用 CREATE TABLE 命令來建立 NoSQL 表格。
下節標示使用 CREATE TABLE DDL 敘述句建立表格時可以使用的不同選項。
範例 1：建立航空公司行李追蹤應用程式表格，其中包含航空公司系統中乘客的行李資訊。
CREATE TABLE BaggageInfo (
ticketNo LONG,
fullName STRING,
gender STRING,
contactPhone STRING,
confNo STRING,
bagInfo JSON,
PRIMARY KEY (ticketNo)
)在上面的綱要中，您可以使用 CREATE TABLE 敘述句來定義 BaggageInfo 表格。乘客的機票號碼 ticketNo 是表格的主鍵。fullName、gender、contactPhone 和 confNo (保留編號) 欄位會儲存乘客的資訊，這是固定結構的一部分。bagInfo 資料欄是無綱要的 JSON 陣列，代表乘客入住行李的追蹤資訊。
有關航空公司行李追蹤申請的詳情，請參閱航空公司行李追蹤申請。
範例 2：使用 JSON 欄位建立串流媒體服務表格，以追蹤訂戶目前的活動。
CREATE TABLE stream_acct(
acct_id INTEGER,
profile_name STRING,
account_expiry TIMESTAMP(9),
acct_data JSON,
PRIMARY KEY(acct_id)
)USING TTL 5 DAYS在上面的綱要中，您可以使用 CREATE TABLE 敘述句來建立 stream_acct 表格。訂戶的帳戶 ID acct_id 欄位是此表格中的主索引鍵。欄位 profile_name，account_expiry 會儲存檢視權詳細資訊，這是固定綱要的一部分。acct_data 資料欄是無綱要 JSON 欄位，可儲存訂閱者檢視的顯示詳細資訊。
如需串流媒體服務應用程式的詳細資訊，請參閱串流媒體服務 - 永久使用者設定檔存放區。
您也會指定 TTL 值，在此值之後，資料列就會自動到期且不再提供使用。TTL 值必須為 HOURS 或 DAYS。在此綱要中，表格的資料列會在 5 天後到期。
範例 3：使用各種固定結構定義建立串流媒體服務表格。
CREATE TABLE IF NOT EXISTS stream_acct(
acct_id INTEGER,
profile_name STRING,
account_expiry TIMESTAMP(9),
acct_data RECORD (
firstName STRING,
lastName STRING,
country STRING,
shows JSON
),
PRIMARY KEY(acct_id)
)在上方的綱要中，您可以將 acct_data 欄位包括為 RECORD 資料類型，以定義固定綱要的變化。
記錄是一或多個索引鍵 - 項目組的排序集合。記錄中的索引鍵必須是字串，且關聯的項目可以是不同的資料類型。記錄中的欄位是固定結構的一部分，您將無法新增或移除這些欄位。在上述範例中，firstName、lastName、country 和 shows 欄位是 acct_data 記錄的關鍵碼。當您要將資料儲存為更大資料集的一部分時，定義記錄非常有用。您可以使用欄位步驟表示式來插入 / 更新 / 擷取記錄中的整個子集。
您也可以依下列方式建立記錄的巢狀結構：
CREATE TABLE IF NOT EXISTS stream_acct(
acct_id INTEGER,
profile_name STRING,
account_expiry TIMESTAMP(9),
acct_data RECORD (
firstName STRING,
lastName STRING,
country STRING,
shows RECORD (
showName STRING,
showId INTEGER,
type JSON,
numSeasons INTEGER,
seriesInfo ARRAY(JSON)
)
),
PRIMARY KEY(acct_id)
)shows 欄位是巢狀 RECORD 類型，用來追蹤所檢視顯示項目的詳細資料。
範例 4：建立串流媒體服務表格作為階層式表格結構。
在下列綱要中，您可以將 stream_acct 表格建立為父項表格，並將 acct_data 表格建立為子項表格：
CREATE TABLE IF NOT EXISTS stream_acct(
acct_id INTEGER,
profile_name STRING,
account_expiry TIMESTAMP(9),
PRIMARY KEY(acct_id))CREATE TABLE IF NOT EXISTS stream_acct.acct_data(
profile_id INTEGER,
user_name STRING,
firstName STRING,
lastName STRING,
country STRING,
shows JSON,
PRIMARY KEY(profile_id))使用上面的父項 - 子項表格定義，串流媒體服務可支援單一訂閱下的多個使用者設定檔。
您可以將 acct_data 表格定義為主索引鍵為 profile_id 的子項表格，以識別使用者的設定檔。除了定義表格的主索引鍵之外，acct_data 表格會隱含繼承其父項 stream_acct 表格的 acct_id 主索引鍵資料欄。
您可以在相同的 stream_acct 父項表格底下定義多個子項表格。您可以進一步定義 acct_data 表格的子項表格。階層中的所有表格都具有相同的分區索引鍵資料欄，此資料欄是在階層中最高父項表格的 create table 敘述句中指定。在此範例中，父項表格的主索引鍵 acct_id 也是 stream_acct 和 acct_data 表格的分區索引鍵。
範例 5：建立主索引鍵為 IDENTITY 資料欄的串流媒體服務表格。
CREATE TABLE IF NOT EXISTS stream_acct(
acct_id INTEGER GENERATED BY DEFAULT AS IDENTITY (START WITH 4 INCREMENT BY 1 NO CYCLE),
profile_name STRING,
account_expiry TIMESTAMP(9),
acct_data JSON,
PRIMARY KEY(acct_id)
)在此範例中，您將使用「範例 2」中定義的相同欄位建立 stream_acct 表格。不過，綱要會將主索引鍵 acct_id 定義為 IDENTITY 資料欄。當您將 IDENTITY 欄定義為 GENERATED BY DEFAULT AS IDENTITY 時，若未提供 IDENTITY 欄值，系統會自動產生 IDENTITY 欄值。系統會從 4 遞增 1 開始產生 acct_id 值。因此，acct_id 資料欄的值將會是 4、5、6... 等等，直到 LONG 資料類型的最大值為止。由於綱目定義「無 CYCLE」選項，系統會在達到順序產生器結束時的最大值之後發出例外。
範例 6：建立主索引鍵為 UUID 資料類型的串流媒體服務表格。
CREATE TABLE IF NOT EXISTS stream_acct(
acct_id STRING AS UUID GENERATED BY DEFAULT,
profile_name STRING,
account_expiry TIMESTAMP(9),
acct_data JSON,
PRIMARY KEY(acct_id)
)在此範例中，您將使用「範例 2」中定義的相同欄位建立 stream_acct 表格。不過，綱要會將主索引鍵 acct_id 定義為 UUID 資料類型，由 DEFAULT 產生。如果您未提供 UUID 欄的值，系統會自動產生該值。將主索引鍵定義為 UUID 資料類型的潛在優點是，系統僅保證區域中 NoSQL 資料存放區內 IDENTITY 資料欄的唯一性，UUID 資料類型會為橫跨多個區域之表格中的記錄產生全域唯一 ID。
JSON 集合表
範例 7：將串流媒體服務表格建立為 JSON 收集表格。
在下列 CREATE TABLE 敘述句中，您可以建立 stream_acct 表格作為 JSON 集合表格：
CREATE TABLE IF NOT EXISTS stream_acct(
acct_id INTEGER,
PRIMARY KEY(acct_id)) AS JSON COLLECTION此 JSON 集合表格包含 acct_id 作為主索引鍵欄位。除了 DDL 命令的主索引鍵欄位之外，不需要提供任何其他欄位。
將資料插入此表格時，JSON 收集表格會自動將 acct_id 欄位以外的插入欄位視為 JSON 欄位。您可以使用此 JSON 收集表格，以純文字形式儲存和擷取電視串流資料。
範例 8：將購物應用程式表格建立為 JSON 集合表格。
下列 CREATE TABLE 敘述句定義一個 storeAcct 表格，這是為購物應用程式建立的 JSON 集合表格。此表格包含 contactPhone 作為類型字串的主索引鍵欄位。
CREATE TABLE storeAcct(
contactPhone string,
primary key(contactPhone)) AS JSON COLLECTION使用 TableRequest API
您可以使用 TableRequest API 建立 NoSQL 表格。
TableRequest 類別是用來建立表格。此要求所指定的作業執行為非同步。這些作業可能會長時間執行。TableResult 會從 TableRequest 作業傳回，且會封裝表格的狀態。請參閱 Oracle NoSQL Java SDK API Reference ，瞭解 TableRequest 類別及其方法的詳細資訊。
Download the full code CreateTable.java from the examples here.
private static void createTab(NoSQLHandle handle) throws Exception {
String createTableDDL =
"CREATE TABLE IF NOT EXISTS " + tableName +
"(acct_Id INTEGER," +
"profile_name STRING," +
"account_expiry TIMESTAMP(1) ," +
"acct_data JSON, " +
"PRIMARY KEY(acct_Id))";
TableLimits limits = new TableLimits(20, 20, 1);
TableRequest treq = new TableRequest()
.setStatement(createTableDDL)
.setTableLimits(limits);
TableResult tres = handle.tableRequest(treq);
/* The request is async,
* so wait for the table to become active.
*/
tres.waitForCompletion(handle, 60000,1000);
System.out.println("Created Table: " + tableName);
}注意：表格限制僅適用於 Oracle NoSQL Database Cloud Service。如果為內部部署 NoSQL 資料庫設定了限制，系統就會以無訊息方式忽略這些限制。
建立子項表格：您可以使用相同的 TableRequest 類別和方法來執行 DDL 敘述句，以建立子項表格。
建立子項表格時：
-
您必須指定表格的完整名稱 (name_parent_table.name_child_table)
-
您不需要明確設定表格限制，因為子項表格會繼承父項表格的限制。
從範例下載完整程式碼 TableJoins.java，以瞭解如何在此建立父項子項表格。
建立 JSON 集合表格：
JSON 集合表格包含一或多個主索引鍵欄位和 JSON 欄位的文件。下列範例會將 stream_acct 表格建立為 JSON 集合表格：
/* Create a JSON collection table with an integer primary key */
private static void createTable(NoSQLHandle handle) throws Exception {
String createTableDDL =
"CREATE TABLE IF NOT EXISTS " + tableName +
"(acct_Id INTEGER, PRIMARY KEY(acct_Id)) AS JSON COLLECTION";
TableRequest treq = new TableRequest().setStatement(createTableDDL);
System.out.println("Creating table");
TableResult tres = handle.tableRequest(treq);
/* The table request is asynchronous, so wait for the table to become active. */
TableResult.waitForState(handle, tres.getTableName(), TableResult.State.ACTIVE, 60000, 1000);
}borneo.TableRequest 類別是用來建立表格。所有對 borneo.NoSQLHandle.table_request() 的呼叫都是非同步的，因此必須檢查結果並呼叫 borneo.TableResult.wait_for_completion()，以等待作業完成。請參閱 Oracle NoSQL Python SDK API Reference ，瞭解 table_request 及其方法的詳細資訊。
從此處的範例下載完整代碼 CreateTable.py 。
def create_table(handle):
statement = '''create table if not exists
stream_acct (acct_Id INTEGER,
profile_name STRING,
account_expiry TIMESTAMP(1),
acct_data JSON,
primary key(acct_Id))'''
request = TableRequest().set_statement(statement)
.set_table_limits(TableLimits(20, 10, 1))
table_result = handle.do_table_request(request, 40000, 3000)
table_result.wait_for_completion(handle, 40000, 3000)
if (table_result.get_state() == State.ACTIVE):
print('Created table: stream_acct')
else:
raise NameError('Table stream_acct is in an unexpected state ' +
str(table_result.get_state()))注意：表格限制僅適用於 Oracle NoSQL Database Cloud Service。如果為內部部署 NoSQL 資料庫設定了限制，系統就會以無訊息方式忽略這些限制。
建立子項表格：您可以使用相同的 TableRequest 類別和方法來執行 DDL 敘述句，以建立子項表格。
建立子項表格時：
-
您必須指定表格的完整名稱 (name_parent_table.name_child_table)。
-
您不需要明確設定表格限制，因為子項表格會繼承父項表格的限制。
從此處的範例下載完整代碼 TableJoins.py 。
建立 JSON 集合表格：
JSON 集合表格包含一或多個主索引鍵欄位和 JSON 欄位的文件。下列範例會將 stream_acct 表格建立為 JSON 集合表格：
# Create a JSON collection table with an integer primary key
statement = '''CREATE TABLE IF NOT EXISTS stream_acct
(acct_Id INTEGER, PRIMARY KEY(acct_Id))
AS JSON COLLECTION'''
print('Creating table: ' + statement)
request = TableRequest().set_statement(statement)
# Wait for 60 seconds, polling every 1 second
result = handle.do_table_request(request, 60000, 1000)
result.wait_for_completion(handle, 60000, 1000)
print('Created table: stream_acct')TableRequest 類別是用來建立表格。TableRequest 指定的作業執行為非同步。這些作業可能會長時間執行。此要求是用來作為 Client.DoTableRequest() 作業的輸入，它會傳回可用來輪詢的 TableResult，直到表格達到所需的狀態為止。請參閱 Oracle NoSQL Go SDK API Reference ，瞭解 TableRequest 類別各種方法的詳細資訊。
從此處的範例下載完整程式碼 CreateTable.go 。
func createTable(client *nosqldb.Client, err error, tableName string)(){
// Creates a table
stmt := fmt.Sprintf("CREATE TABLE IF NOT EXISTS %s ("+
"acct_Id INTEGER," +
"profile_name STRING," +
"account_expiry TIMESTAMP(1) ," +
"acct_data JSON, " +
"PRIMARY KEY(acct_Id))",tableName)
tableReq := &nosqldb.TableRequest{
Statement: stmt,
TableLimits: &nosqldb.TableLimits{
ReadUnits: 20,
WriteUnits: 20,
StorageGB: 1,
},
}
tableRes, err := client.DoTableRequest(tableReq)
if err != nil {
fmt.Printf("cannot initiate CREATE TABLE request: %v\n", err)
return
}
// The create table request is asynchronous,
// wait for table creation to complete.
_, err = tableRes.WaitForCompletion(client, 60*time.Second, time.Second)
if err != nil {
fmt.Printf("Error finishing CREATE TABLE request: %v\n", err)
return
}
fmt.Println("Created table: ", tableName)
return
}注意：表格限制僅適用於 Oracle NoSQL Database Cloud Service。如果為內部部署 NoSQL 資料庫設定了限制，系統就會以無訊息方式忽略這些限制。
建立子項表格：您可以使用相同的 TableRequest 類別和方法來執行 DDL 敘述句，以建立子項表格。
建立子項表格時：
-
您必須指定表格的完整名稱 (name_parent_table.name_child_table)。
-
您不需要明確設定表格限制，因為子項表格會繼承父項表格的限制。
從此處的範例下載完整代碼 TableJoins.go 。
建立 JSON 集合表格：
JSON 集合表格包含一或多個主索引鍵欄位和 JSON 欄位的文件。下列範例會將 stream_acct 表格建立為 JSON 集合表格：
/* Create a JSON collection table with an integer primary key */
func createTable(client *nosqldb.Client) error {
tableName := "stream_acct"
stmt := fmt.Sprintf(
"CREATE TABLE IF NOT EXISTS %s "+
"(acct_Id INTEGER, PRIMARY KEY(acct_Id)) "+
"AS JSON COLLECTION",
tableName,
)
fmt.Println("Creating table:", stmt)
tableReq := &nosqldb.TableRequest{
Statement: stmt,
}
tableRes, err := client.DoTableRequest(tableReq)
if err != nil {
return err
}
// Wait for 60 seconds, polling every 1 second.
_, err = tableRes.WaitForCompletion(
client,
60*time.Second,
time.Second,
)
if err != nil {
return err
}
fmt.Println("Created table:", tableName)
return nil
}您可以使用 tableDDL 方法建立表格。此方法為非同步，且會傳回 Promise TableResult。TableResult 是包含 DDL 作業狀態 (例如其 TableState、名稱、綱要及其 TableLimits) 的純 JavaScript 物件。如需方法詳細資訊，請參閱 NoSQLClient 類別。
tableDDL 方法會使用 TableDDLOpt 物件作為第二個選擇性引數。建立表格時，您必須指定其 TableLimits 作為 opt 引數的一部分。TableLimits 會將表格的最大傳輸量和儲存容量指定為讀取單位、寫入單位和儲存大小 (GB)。
從此處的範例及此處的完整 TypeScript 程式碼 CreateTable.js 下載完整的 JavaScript 程式碼 CreateTable.js。
import {NoSQLClient, TableState } from 'oracle-nosqldb';
const client = new NoSQLClient('config.json');
const TABLE_NAME = 'stream_acct;
async function createTable(handle) {
const createDDL = `CREATE TABLE IF NOT EXISTS
${TABLE_NAME} (acct_Id INTEGER,
profile_name STRING,
account_expiry TIMESTAMP(1),
acct_data JSON,
primary key(acct_Id))`;
/* For Provisioned Capacity specify read units, write units, and storage limit as shown below*/
/* For On-demand Capacity - set only the storage limit and specify the mode as shown here.
* { storageGB: 25, mode: CapacityMode.ON_DEMAND };
*/
let res = await handle.tableDDL(createDDL, {
complete: true,
tableLimits: {
readUnits: 20,
writeUnits: 20,
storageGB: 1
}
});
console.log('Created table: ' + TABLE_NAME);
}在上述回電之後，結果將反映作業的最終狀態。或者，若要使用完整選項，請將上述 try-catch 區塊中的程式碼取代為下列程式碼範例。
const createDDL = `CREATE TABLE IF NOT EXISTS
${TABLE_NAME} (acct_Id INTEGER,
profile_name STRING,
account_expiry TIMESTAMP(1),
acct_data JSON,
primary key(acct_Id))`;
let res = await client.tableDDL(createDDL, {complete: true,});
console.log('Created table: ' + TABLE_NAME);建立子項表格：您可以使用相同的 TableRequest 類別和方法來執行 DDL 敘述句，以建立子項表格。
建立子項表格時：
-
您必須指定表格的完整名稱 (name_parent_table.name_child_table)
-
您不需要明確設定表格限制，因為子項表格會繼承父項表格的限制。
Download the full JavaScript code TableJoins.js from the examples here and the full TypeScript code TableJoins.ts from the examples here.
建立 JSON 集合表格：
JSON 集合表格包含一或多個主索引鍵欄位和 JSON 欄位的文件。下列範例會將 stream_acct 表格建立為 JSON 集合表格：
/* Create a JSON collection table with an integer primary key */
const client = new NoSQLClient('config.json');
const TABLE_NAME = 'stream_acct';
async function createTable() {
const createDDL =
`CREATE TABLE IF NOT EXISTS ${TABLE_NAME} ` +
`(acct_Id INTEGER, PRIMARY KEY(acct_Id)) ` +
`AS JSON COLLECTION`;
console.log('Create table: ' + createDDL);
try {
await client.tableDDL(createDDL, {
complete: true
});
console.log('Created table: ' + TABLE_NAME);
} catch (error) {
console.error('Table creation failed:', error);
throw error;
}
}若要建立表格，請使用 ExecuteTableDDLAsync 或 ExecuteTableDDLWithCompletionAsync 方法。這兩種方法都會傳回 Task<TableResult>。TableResult 執行處理包含 DDL 作業的狀態，例如 TableState 和表格綱要。如需這些方法的詳細資訊，請參閱 Oracle NoSQL Dotnet SDK API Reference 。
Download the full code CreateTable.cs from the examples here.
private static async Task createTable(NoSQLClient client){
// Create a table
var sql =
$@"CREATE TABLE IF NOT EXISTS
{TableName}(acct_Id INTEGER,
profile_name STRING,
account_expiry TIMESTAMP(1),
acct_data JSON,
primary key(acct_Id))";
var tableResult = await client.ExecuteTableDDLAsync(sql,
new TableDDLOptions{TableLimits = new TableLimits(20, 20, 1)});
// Wait for the operation completion
await tableResult.WaitForCompletionAsync();
Console.WriteLine(" Created table: ",tableResult.TableName);
}注意：表格限制僅適用於 Oracle NoSQL Database Cloud Service。如果為內部部署 NoSQL 資料庫設定了限制，系統就會以無訊息方式忽略這些限制。
建立子項表格：您可以使用相同的 TableRequest 類別和方法來執行 DDL 敘述句，以建立子項表格。
建立子項表格時：
-
您必須指定表格的完整名稱 (name_parent_table.name_child_table)
-
您不需要明確設定表格限制，因為子項表格會繼承父項表格的限制。
Download the full code TableJoins.cs from the examples here.
建立 JSON 集合表格：
JSON 集合表格包含一或多個主索引鍵欄位和 JSON 欄位的文件。下列範例會將 stream_acct 表格建立為 JSON 集合表格：
/* Create a JSON collection table with an integer primary key */
private static async Task CreateTableAsync(NoSQLClient client)
{
const string tableName = "stream_acct";
var statement =
$"CREATE TABLE IF NOT EXISTS {tableName} " +
"(acct_Id INTEGER, PRIMARY KEY(acct_Id)) " +
"AS JSON COLLECTION";
Console.WriteLine($"Creating table: {statement}");
var result = await client.ExecuteTableDDLAsync(statement);
await result.WaitForCompletionAsync();
Console.WriteLine($"Table {tableName} created.");
}