Table Store SDK には、PutRow、GetRow、UpdateRow および DeleteRow の単一行操作インターフェイスがあります。
PutRow
指定された行にデータを挿入します。
API
/// <summary>
/// 指定されたテーブル名、プライマリキー、および属性に基づいてデータ行を書き込みます。 操作によって消費された CapacityUnit が返されます。
/// </summary>
///<param name = "request"> データ挿入要求 </param>
///<returns> 操作によって消費された CapacityUnit です。 <returns>
public PutRowResponse PutRow(PutRowRequest request);
/// <summary>
/// PutRow の非同期形式です。
/// </summary>
public Task<PutRowResponse> PutRowAsync(PutRowRequest request);
例 1
データ行を挿入します。
// 行のプライマリキーを定義します。これは、テーブル作成時に TableMeta で定義されたプライマリキーと一致している必要があります。
var primaryKey = new PrimaryKey();
primaryKey.Add("pk0", new ColumnValue(0));
primaryKey.Add("pk1", new ColumnValue("abc"));
// 100 行の属性列を定義します。
var attribute = new AttributeColumns();
attribute.Add("col0", new ColumnValue(0));
attribute.Add("col1", new ColumnValue("a"));
attribute.Add("col2", new ColumnValue(true));
try
{
// RowExistenceExpectation.IGNORE を使用して、指定された行が存在しない場合でもデータがまだ挿入されていることを示すデータ挿入用のリクエストオブジェクトを作成します。
var request = new PutRowRequest("SampleTable", new Condition(RowExistenceExpectation.IGNORE),
primaryKey, attribute);
// PutRow を呼び出してデータを挿入します。
otsClient.PutRow(request);
// 例外がスローされなければ、実行は成功します。
Console.WriteLine("Put row succeeded.");
}
catch (Exception ex)
{
// 例外がスローされてエラーメッセージが表示されると、実行は失敗します。
Console.WriteLine("Put row failed, exception:{0}", ex.Message);
}
-
Condition.IGNORE、Condition.EXPECT_EXIST および Condition.EXPECT_NOT_EXISTは、v3.0.0 から非推奨になりました。 代わりに、新しい条件 (RowExistenceExpectation.IGNORE)、新しい条件 (RowExistenceExpectation.EXPECT_EXIST) および新しい条件(RowExistenceExpectation.EXPECT_NOT_EXIST) を使用してください。
-
RowExistenceExpectation.IGNORE は、指定された行が存在しない場合でも新しいデータが挿入されることを示します。 挿入されたデータが既存のデータと同じ場合、既存のデータは上書きされます。
-
RowExistenceExpectation.EXPECT_EXIST は、指定された行が存在する場合にのみ新しいデータが挿入されることを示します。 既存のデータは上書きされます。
-
RowExistenceExpectation.EXPECT_NOT_EXIST は、指定された行が存在しない場合にのみデータが挿入されることを示します。
-
行条件に加えて、Condition パラメーターは v2.2.0 以降の列条件もサポートします。
コードの詳細は、『PutRow@GitHub』をご参照ください。
例 2
指定した条件に基づいてデータ行を挿入します。
次のコード例は、指定された行が存在し、col1 の値が 24 より大きい場合にのみデータを挿入します。
// 行のプライマリキーを定義します。これは、テーブル作成時に TableMeta で定義されたプライマリキーと一致している必要があります。
var primaryKey = new PrimaryKey();
primaryKey.Add("pk0", new ColumnValue(0));
primaryKey.Add("pk1", new ColumnValue("abc"));
// 100 行の属性列を定義します。
AttributeColumns attribute = new AttributeColumns();
attribute.Add("col0", new ColumnValue(0));
attribute.Add("col1", new ColumnValue("a"));
attribute.Add("col2", new ColumnValue(true));
var request = new PutRowRequest(tableName, new Condition(RowExistenceExpectation.EXPECT_EXIST),
primaryKey, attribute);
// col0 の値が 24 より大きい場合は、PutRow が再度実行されて元の値が上書きされます。
try
{
request.Condition.ColumnCondition = new RelationalCondition("col0",
RelationalCondition.CompareOperator.GREATER_THAN,
new ColumnValue(24));
otsClient.PutRow(request);
Console.WriteLine("Put row succeeded.");
}
catch (Exception ex)
{
Console.WriteLine("Put row failed. error:{0}", ex.Message);
}
-
単一の条件または条件の組み合わせを設定できます。 たとえば、col1 > 5 および pk2 < 'xyz' として2つのデータ挿入条件を設定できます。
-
属性列と主キー列は、Condition パラメーターをサポートしています。
-
条件で指定された列が行に存在しない場合は、RelationCondition の PassIfMissing が実行するアクションを制御します。 デフォルト値は true です。
コードの詳細は、ConditionPutRow@GitHub』をご参照ください。
例 3
データ行を非同期に挿入します。
try
{
var putRowTaskList = new List<Task<PutRowResponse>>();
for (int i = 0; i < 100; i++)
{
// 行のプライマリキーを定義します。これは、テーブル作成時に TableMeta で定義されたプライマリキーと一致している必要があります。
var primaryKey = new PrimaryKey();
primaryKey.Add("pk0", new ColumnValue(i));
primaryKey.Add("pk1", new ColumnValue("abc"));
// 100 行の属性列を定義します
var attribute = new AttributeColumns();
attribute.Add("col0", new ColumnValue(i));
attribute.Add("col1", new ColumnValue("a"));
attribute.Add("col2", new ColumnValue(true));
var request = new PutRowRequest(TableName, new Condition(RowExistenceExpectation.IGNORE),
primaryKey, attribute);
putRowTaskList.Add(TabeStoreClient.PutRowAsync(request));
}
// 各非同期呼び出しが結果を返すまで待機し、消費された CU を表示します。
foreach (var task in putRowTaskList)
{
task.Wait();
Console.WriteLine("consumed read:{0}, write:{1}", task.Result.ConsumedCapacityUnit.Read,
task.Result.ConsumedCapacityUnit.Write);
}
// 例外がスローされない場合、データは正常に挿入されます。
Console.WriteLine("Put row async succeeded.");
}
catch (Exception ex)
{
// 例外がスローされるとエラーメッセージが表示されます。
Console.WriteLine("Put row async failed. exception:{0}", ex.Message);
}
コードの詳細は、『PutRowAsync@GitHub』をご参照ください。
GetRow
指定された主キーに基づいて単一のデータ行を読み取ります。
API
/// <summary>
/// 指定されたプライマリキーに基づいて単一のデータ行を読み取ります。
/// </summary>
/// <param name="request"> データクエリリクエスト </param>
///<returns> GetRow から返された応答 </returns>
public GetRowResponse GetRow(GetRowRequest request);
/// <summary>
/// GetRow の非同期形式
/// </summary>
public Task<GetRowResponse> GetRowAsync(GetRowRequest request);
例 1
データ行を読み取ります。
// 行のプライマリキーを定義します。これは、テーブル作成時に TableMeta で定義されたプライマリキーと一致している必要があります。
PrimaryKey primaryKey = new PrimaryKey();
primaryKey.Add("pk0", new ColumnValue(0));
primaryKey.Add("pk1", new ColumnValue("abc"));
try
{
// クエリリクエストオブジェクトを作成します。 列が指定されていない場合は、行全体が読み取られます。
var request = new GetRowRequest(TableName, primaryKey);
// データを問い合わせるために GetRow インターフェイスを呼び出します。
var response = otsClient.GetRow(request);
// 行のデータを出力します。 出力データはここでは省略されています。 詳しくは、GitHub のリンクをご参照ください。
// 例外がスローされなければ、データは正常に読み取られます。
Console.WriteLine("Get row succeeded.");
}
catch (Exception ex)
{
// 例外がスローされてエラーメッセージが表示されると、実行は失敗します
Console.WriteLine("Update table failed, exception:{0}", ex.Message);
}
-
データ行をクエリすると、システムはその行のすべての列のデータを返します。 columnsToGet パラメーターを使用して、指定した列のデータを読み取ることができます。 たとえば、col0 と col1 が columnsToGet に挿入された場合、システムは col0 と col1 のデータのみを返します。
-
条件付きフィルタがサポートされています。 たとえば、col0 の値が 24 より大きい場合にのみ結果を返すようにシステムを設定できます。
-
columnsToGet パラメーターと Condition パラメーターの両方が使用されている場合、システムは最初に columnsToGet に基づいて結果を返し、次に Condition パラメーターに基づいて返された列をフィルタリングします。
-
指定された列が存在しない場合、PassIfMissing が次のアクションを決定します。
コードの詳細は、『GetRow@GitHub』をご参照ください。
例 2
フィルター機能を使用してデータ行を読み取ります。
次のコード例は、データを照会し、col0 と col1 のデータのみを返し、col0 の値が 24 であるという条件に基づいて col0 のデータをフィルタリングするようにシステムを設定します。
// 行のプライマリキーを定義します。これは、テーブル作成時に TableMeta で定義されたプライマリキーと一致している必要があります。
PrimaryKey primaryKey = new PrimaryKey();
primaryKey.Add("pk0", new ColumnValue(0));
primaryKey.Add("pk1", new ColumnValue("abc"));
var rowQueryCriteria = new SingleRowQueryCriteria("SampleTable");
rowQueryCriteria.RowPrimaryKey = primaryKey;
// 条件 1 は col0 の値が 5 であることです。
var filter1 = new RelationalCondition("col0",
RelationalCondition.CompareOperator.EQUAL,
new ColumnValue(5));
// 条件 2 は col1 の値が ff ではないことです。
var filter2 = new RelationalCondition("col1", RelationalCondition.CompareOperator.NOT_EQUAL, new ColumnValue("ff"));
// 条件 1 と条件 2 の組み合わせを OR 関係で構築します。
var filter = new CompositeCondition(CompositeCondition.LogicOperator.OR);
filter.AddCondition(filter1);
filter.AddCondition(filter2);
rowQueryCriteria.Filter = filter;
// 条件 [col0, col1] に基づいてクエリする行を設定し、指定された条件に基づいてクエリされたデータをフィルタリングします。
rowQueryCriteria.AddColumnsToGet("col0");
rowQueryCriteria.AddColumnsToGet("col1");
// GetRowRequest を構築します。
var request = new GetRowRequest(rowQueryCriteria);
try
{
// クエリデータ
var response = otsClient.GetRow(request);
// データの出力または関連する論理演算の実行をします (省略)。
// 例外がスローされなければ、実行は成功します。
Console.WriteLine("Get row with filter succeeded.");
}
catch (Exception ex)
{
// 例外がスローされてエラーメッセージが表示されると、実行は失敗します
Console.WriteLine("Get row with filter failed, exception:{0}", ex.Message);
}
コードの詳細は、『GetRowWithFilter@GitHub』をご参照ください。
UpdateRow
指定された行のデータを更新します。 指定された行が存在しない場合は、新しい行が追加されます。 それ以外の場合は、指定された列の値は、リクエストに合わせて、追加、変更、又は削除されます。
API
/// <summary>
/// 指定された行のデータを更新します。 指定された行が存在しない場合は、新しい行が追加されます。 指定された行が存在する場合は、指定された列の値は、リクエストに合わせて、追加、変更、又は削除されます。
/// </summary>
///<param name = "request"> リクエストインスタンス </param>
public UpdateRowResponse UpdateRow(UpdateRowRequest request);
/// <summary>
/// UpdateRow の非同期形式です。
/// </summary>
/// <param name="request"></param>
/// <returns></returns>
public Task<UpdateRowResponse> UpdateRowAsync(UpdateRowRequest request);
例
指定された行のデータを更新します。
// 行のプライマリキーを定義します。これは、テーブル作成時に TableMeta で定義されたプライマリキーと一致している必要があります。
PrimaryKey primaryKey = new PrimaryKey();
primaryKey.Add("pk0", new ColumnValue(0));
primaryKey.Add("pk1", new ColumnValue("abc"));
// 100 行の属性列を定義します。
UpdateOfAttribute attribute = new UpdateOfAttribute();
attribute.AddAttributeColumnToPut("col0", new ColumnValue(0));
attribute.AddAttributeColumnToPut("col1", new ColumnValue("b")); // Change the original value 'a' to 'b'
attribute.AddAttributeColumnToPut("col2", new ColumnValue(true));
try
{
// 指定された行が存在しない場合でもデータがまだ更新されていることを示す RowExistenceExpectation.IGNORE を使用して、行更新用の要求オブジェクトを作成します。
var request = new UpdateRowRequest(TableName, new Condition(RowExistenceExpectation.IGNORE),
primaryKey, attribute);
// UpdateRow インターフェイスを呼び出します。
otsClient.UpdateRow(request);
// 例外がスローされなければ、実行は成功します。
Console.Writeline("Update row succeeded.");
}
catch (Exception ex)
{
// 例外がスローされてエラーメッセージが表示されると、実行は失敗します
Console.WriteLine("Update row failed, exception:{0}", ex.Message);
}
コードの詳細は、『UpdateRow@GitHub』をご参照ください。
DeleteRow
API
(delete)/// <summary>(delete)
/// 指定されたテーブル名とプライマリキーに基づいてデータ行を削除します。
/// </summary>
/// <param name = "request"> リクエストインスタンス </param>
/// <returns> レスポンスインスタンス </returns/>
public DeleteRowResponse DeleteRow(DeleteRowRequest request);
/// <summary>
/// DeleteRow の非同期形式です。
/// </summary>
public Task<DeleteRowResponse> DeleteRowAsync(DeleteRowRequest request);
例
データ行を削除します。
// 削除する行のプライマリキー列の値は 0 と "abc" です。
var primaryKey = new PrimaryKey();
primaryKey.Add("pk0", new ColumnValue(0));
primaryKey.Add("pk1", new ColumnValue("abc"));
try
{
// 行が存在する場合にのみ行が削除されることを示す Condition.EXPECT_EXIST を使用して要求を作成します。
var deleteRowRequest = new DeleteRowRequest("SampleTable", Condition.EXPECT_EXIST, primaryKey);
// DeleteRow インターフェイスを呼び出して行を削除します。
otsClient.DeleteRow(deleteRowRequest);
// 例外がスローされない場合、行は正常に削除されます。
Console.Writeline("Delete table succeeded.");
}
catch (Exception ex)
{
// 例外がスローされた場合、行は削除されず、エラーメッセージが表示されます。
Console.WriteLine("Delete table failed, exception:{0}", ex.Message);
}
コードの詳細は、『DeleteRow@GitHub』をご参照ください。