Azure Cosmos DB でストアドプロシージャ、トリガー、およびユーザー定義関数を登録および使用する方法

2025-07-10

適用対象: NoSQL

Azure Cosmos DB の NoSQL 用 API は、JavaScript で記述されたストアドプロシージャ、トリガー、およびユーザー定義関数 (UDF) の登録および呼び出しをサポートします。 1 つ以上のストアドプロシージャ、トリガー、または UDF を定義したら、データエクスプローラーを使用して Azure portal で読み込んで表示できます。

これらのタスクを実行するには、.NET v2 (レガシ)、.NET v3、Java、JavaScript 、Python SDK など、複数のプラットフォームで NoSQL SDK 用 API を使用できます。これらの SDK を使用したことがない場合は、該当する SDK のクイックスタートの記事を参照してください。

SDK	クイックスタート
.NET v3	NoSQL 用 Azure Cosmos DB クライアントライブラリ for .NET
Java	Azure Cosmos DB for NoSQL データを管理する Java アプリを構築する
JavaScript	Node.js用 Azure Cosmos DB for NoSQL クライアントライブラリ
Python	Python 用 Azure Cosmos DB for NoSQL クライアントライブラリ

重要

次のコードサンプルでは、既に client 変数と container 変数があることを前提としています。これらの変数を作成する必要がある場合は、プラットフォームに適したクイックスタートをご覧ください。

ストアドプロシージャの実行方法

ストアドプロシージャは JavaScript を使用して記述されます。これらは Azure Cosmos DB コンテナー内部で作成、更新、読み取り、クエリの実行、および削除できます。詳細については、「ストアドプロシージャを記述する方法」を参照してください。

次の例では、Azure Cosmos DB SDK を使用してストアドプロシージャを登録および呼び出す方法を示します。 spCreateToDoItem.js として保存されたこの例のソースについては、「ストアドプロシージャを使用して項目を作成する」を参照してください。

Note

パーティション分割されたコンテナーの場合、ストアドプロシージャを実行するとき、要求オプションにパーティションキー値を指定する必要があります。ストアドプロシージャは常に 1 つのパーティションキーに範囲設定されます。別のパーティションキー値を持つ項目は、ストアドプロシージャから認識できません。この原則は、トリガーにも当てはまります。

次の例は、.NET SDK v2 を使用してストアドプロシージャを登録する方法を示しています。

string storedProcedureId = "spCreateToDoItems";
StoredProcedure newStoredProcedure = new StoredProcedure
   {
       Id = storedProcedureId,
       Body = File.ReadAllText($@"..\js\{storedProcedureId}.js")
   };
Uri containerUri = UriFactory.CreateDocumentCollectionUri("myDatabase", "myContainer");
var response = await client.CreateStoredProcedureAsync(containerUri, newStoredProcedure);
StoredProcedure createdStoredProcedure = response.Resource;

次のコードは、.NET SDK v2 を使用してストアドプロシージャを呼び出す方法を示しています。

dynamic[] newItems = new dynamic[]
{
    new {
        category = "Personal",
        name = "Groceries",
        description = "Pick up strawberries",
        isComplete = false
    },
    new {
        category = "Personal",
        name = "Doctor",
        description = "Make appointment for check up",
        isComplete = false
    }
};

Uri uri = UriFactory.CreateStoredProcedureUri("myDatabase", "myContainer", "spCreateToDoItem");
RequestOptions options = new RequestOptions { PartitionKey = new PartitionKey("Personal") };
var result = await client.ExecuteStoredProcedureAsync<string>(uri, options, new[] { newItems });

次の例は、.NET SDK v3 を使用してストアドプロシージャを登録する方法を示しています。

string storedProcedureId = "spCreateToDoItems";
StoredProcedureResponse storedProcedureResponse = await client.GetContainer("myDatabase", "myContainer").Scripts.CreateStoredProcedureAsync(new StoredProcedureProperties
{
    Id = storedProcedureId,
    Body = File.ReadAllText($@"..\js\{storedProcedureId}.js")
});

次のコードは、.NET SDK v3 を使用してストアドプロシージャを呼び出す方法を示しています。

dynamic[] newItems = new dynamic[]
{
    new {
        category = "Personal",
        name = "Groceries",
        description = "Pick up strawberries",
        isComplete = false
    },
    new {
        category = "Personal",
        name = "Doctor",
        description = "Make appointment for check up",
        isComplete = false
    }
};

var result = await client.GetContainer("database", "container").Scripts.ExecuteStoredProcedureAsync<string>("spCreateToDoItem", new PartitionKey("Personal"), new[] { newItems });

次の例は、Java SDK を使用してストアドプロシージャを登録する方法を示しています。

CosmosStoredProcedureProperties definition = new CosmosStoredProcedureProperties(
    "spCreateToDoItems", 
    Files.readString(Paths.get("createToDoItems.js"))
);

CosmosStoredProcedureResponse response = container
    .getScripts()
    .createStoredProcedure(definition);

次のコードは、Java SDK を使用してストアドプロシージャを呼び出す方法を示しています。

CosmosStoredProcedure sproc = container   
    .getScripts()
    .getStoredProcedure("spCreateToDoItems");

List<Object> items = new ArrayList<Object>();

ToDoItem firstItem = new ToDoItem();
firstItem.category = "Personal";
firstItem.name = "Groceries";
firstItem.description = "Pick up strawberries";
firstItem.isComplete = false;
items.add(firstItem);

ToDoItem secondItem = new ToDoItem();
secondItem.category = "Personal";
secondItem.name = "Doctor";
secondItem.description = "Make appointment for check up";
secondItem.isComplete = true;
items.add(secondItem);

CosmosStoredProcedureRequestOptions options = new CosmosStoredProcedureRequestOptions();
options.setPartitionKey(
    new PartitionKey("Personal")
);

CosmosStoredProcedureResponse response = sproc.execute(
    items, 
    options
);

次の例は、JavaScript SDK を使用してストアドプロシージャを登録する方法を示しています。

const container = client.database("myDatabase").container("myContainer");
const sprocId = "spCreateToDoItems";
await container.scripts.storedProcedures.create({
    id: sprocId,
    body: require(`../js/${sprocId}`)
});

次のコードは、JavaScript SDK を使用してストアドプロシージャを呼び出す方法を示しています。

const newItem = [{
    category: "Personal",
    name: "Groceries",
    description: "Pick up strawberries",
    isComplete: false
}];
const container = client.database("myDatabase").container("myContainer");
const sprocId = "spCreateToDoItems";
const {resource: result} = await container.scripts.storedProcedure(sprocId).execute(newItem, {partitionKey: newItem[0].category});

次の例は、Python SDK を使用してストアドプロシージャを登録する方法を示しています。

import azure.cosmos.cosmos_client as cosmos_client

url = "your_cosmos_db_account_URI"
key = "your_cosmos_db_account_key"
database_name = 'your_cosmos_db_database_name'
container_name = 'your_cosmos_db_container_name'

with open('../js/spCreateToDoItems.js') as file:
    file_contents = file.read()

sproc = {
    'id': 'spCreateToDoItem',
    'serverScript': file_contents,
}
client = cosmos_client.CosmosClient(url, key)
database = client.get_database_client(database_name)
container = database.get_container_client(container_name)
created_sproc = container.scripts.create_stored_procedure(body=sproc)

次のコードは、Python SDK を使用してストアドプロシージャを呼び出す方法を示しています。

import uuid

new_id= str(uuid.uuid4())

# Creating a document for a container with "id" as a partition key.

new_item =   {
      "id": new_id, 
      "category":"Personal",
      "name":"Groceries",
      "description":"Pick up strawberries",
      "isComplete":False
   }
result = container.scripts.execute_stored_procedure(sproc=created_sproc,params=[new_item], partition_key=new_id)

プリトリガーを実行する方法

次の例は、Azure Cosmos DB SDK を使用してプリトリガーを登録して呼び出す方法を示しています。このプリトリガーの例のソース ( trgPreValidateToDoItemTimestamp.jsとして保存) については、「プリトリガー」を参照してください。

PreTriggerIncludeを指定して操作を実行し、List オブジェクトでトリガーの名前を渡すと、RequestOptions オブジェクトに事前トリガーが渡されます。

Note

トリガーの名前が List として渡される場合でも、操作ごとにトリガーを 1 つだけ実行することができます。

次のコードは、.NET SDK v2 を使用してプリトリガーを登録する方法を示しています。

string triggerId = "trgPreValidateToDoItemTimestamp";
Trigger trigger = new Trigger
{
    Id =  triggerId,
    Body = File.ReadAllText($@"..\js\{triggerId}.js"),
    TriggerOperation = TriggerOperation.Create,
    TriggerType = TriggerType.Pre
};
Uri containerUri = UriFactory.CreateDocumentCollectionUri("myDatabase", "myContainer");
await client.CreateTriggerAsync(containerUri, trigger);

次のコードは、.NET SDK v2 を使用してプリトリガーを呼び出す方法を示しています。

dynamic newItem = new
{
    category = "Personal",
    name = "Groceries",
    description = "Pick up strawberries",
    isComplete = false
};

Uri containerUri = UriFactory.CreateDocumentCollectionUri("myDatabase", "myContainer");
RequestOptions requestOptions = new RequestOptions { PreTriggerInclude = new List<string> { "trgPreValidateToDoItemTimestamp" } };
await client.CreateDocumentAsync(containerUri, newItem, requestOptions);

次のコードは、.NET SDK v3 を使用してプリトリガーを登録する方法を示しています。

await client.GetContainer("database", "container").Scripts.CreateTriggerAsync(new TriggerProperties
{
    Id = "trgPreValidateToDoItemTimestamp",
    Body = File.ReadAllText("@..\js\trgPreValidateToDoItemTimestamp.js"),
    TriggerOperation = TriggerOperation.Create,
    TriggerType = TriggerType.Pre
});

次のコードは、.NET SDK v3 を使用してプリトリガーを呼び出す方法を示しています。

dynamic newItem = new
{
    category = "Personal",
    name = "Groceries",
    description = "Pick up strawberries",
    isComplete = false
};

await client.GetContainer("database", "container").CreateItemAsync(newItem, null, new ItemRequestOptions { PreTriggers = new List<string> { "trgPreValidateToDoItemTimestamp" } });

次のコードは、Java SDK を使用してプリトリガーを登録する方法を示しています。

CosmosTriggerProperties definition = new CosmosTriggerProperties(
    "preValidateToDoItemTimestamp",
    Files.readString(Paths.get("validateToDoItemTimestamp.js"))
);
definition.setTriggerOperation(TriggerOperation.CREATE);
definition.setTriggerType(TriggerType.PRE);

CosmosTriggerResponse response = container
    .getScripts()
    .createTrigger(definition);

次のコードは、Java SDK を使用してプリトリガーを呼び出す方法を示しています。

ToDoItem item = new ToDoItem();
item.category = "Personal";
item.name = "Groceries";
item.description = "Pick up strawberries";
item.isComplete = false;
    
CosmosItemRequestOptions options = new CosmosItemRequestOptions();
options.setPreTriggerInclude(
    Arrays.asList("preValidateToDoItemTimestamp")
);

CosmosItemResponse<ToDoItem> response = container.createItem(item, options);

次のコードは、JavaScript SDK を使用してプリトリガーを登録する方法を示しています。

const container = client.database("myDatabase").container("myContainer");
const triggerId = "trgPreValidateToDoItemTimestamp";
await container.scripts.triggers.create({
    id: triggerId,
    body: require(`../js/${triggerId}`),
    triggerOperation: "create",
    triggerType: "pre"
});

次のコードは、JavaScript SDK を使用してプリトリガーを呼び出す方法を示しています。

const container = client.database("myDatabase").container("myContainer");
const triggerId = "trgPreValidateToDoItemTimestamp";
await container.items.create({
    category: "Personal",
    name: "Groceries",
    description: "Pick up strawberries",
    isComplete: false
}, {preTriggerInclude: [triggerId]});

次のコードは、Python SDK を使用してプリトリガーを登録する方法を示しています。

import azure.cosmos.cosmos_client as cosmos_client
from azure.cosmos import documents

url = "your_cosmos_db_account_URI"
key = "your_cosmos_db_account_key"
database_name = 'your_cosmos_db_database_name'
container_name = 'your_cosmos_db_container_name'

with open('../js/trgPreValidateToDoItemTimestamp.js') as file:
    file_contents = file.read()

trigger_definition = {
    'id': 'trgPreValidateToDoItemTimestamp',
    'serverScript': file_contents,
    'triggerType': documents.TriggerType.Pre,
    'triggerOperation': documents.TriggerOperation.All
}
client = cosmos_client.CosmosClient(url, key)
database = client.get_database_client(database_name)
container = database.get_container_client(container_name)
trigger = container.scripts.create_trigger(trigger_definition)

次のコードは、Python SDK を使用してプリトリガーを呼び出す方法を示しています。

item = {'category': 'Personal', 'name': 'Groceries',
        'description': 'Pick up strawberries', 'isComplete': False}

result = container.create_item(item, pre_trigger_include='trgPreValidateToDoItemTimestamp')

ポストトリガーの実行方法

次の例では、Azure Cosmos DB SDK を使用してポストトリガーを登録する方法を示します。このポストトリガー (trgPostUpdateMetadata.js として保存) の例のソースについては、「ポストトリガー」を参照してください

次のコードは、.NET SDK v2 を使用してポストトリガーを登録する方法を示しています。

string triggerId = "trgPostUpdateMetadata";
Trigger trigger = new Trigger
{
    Id = triggerId,
    Body = File.ReadAllText($@"..\js\{triggerId}.js"),
    TriggerOperation = TriggerOperation.Create,
    TriggerType = TriggerType.Post
};
Uri containerUri = UriFactory.CreateDocumentCollectionUri("myDatabase", "myContainer");
await client.CreateTriggerAsync(containerUri, trigger);

次のコードは、.NET SDK v2 を使用してポストトリガーを呼び出す方法を示しています。

var newItem = { 
    name: "artist_profile_1023",
    artist: "The Band",
    albums: ["Hellujah", "Rotators", "Spinning Top"]
};

RequestOptions options = new RequestOptions { PostTriggerInclude = new List<string> { "trgPostUpdateMetadata" } };
Uri containerUri = UriFactory.CreateDocumentCollectionUri("myDatabase", "myContainer");
await client.createDocumentAsync(containerUri, newItem, options);

次のコードは、.NET SDK v3 を使用してポストトリガーを登録する方法を示しています。

await client.GetContainer("database", "container").Scripts.CreateTriggerAsync(new TriggerProperties
{
    Id = "trgPostUpdateMetadata",
    Body = File.ReadAllText(@"..\js\trgPostUpdateMetadata.js"),
    TriggerOperation = TriggerOperation.Create,
    TriggerType = TriggerType.Post
});

次のコードは、.NET SDK v3 を使用してポストトリガーを呼び出す方法を示しています。

var newItem = { 
    name: "artist_profile_1023",
    artist: "The Band",
    albums: ["Hellujah", "Rotators", "Spinning Top"]
};

await client.GetContainer("database", "container").CreateItemAsync(newItem, null, new ItemRequestOptions { PostTriggers = new List<string> { "trgPostUpdateMetadata" } });

次のコードは、Java SDK を使用してポストトリガーを登録する方法を示しています。

CosmosTriggerProperties definition = new CosmosTriggerProperties(
    "postUpdateMetadata",
    Files.readString(Paths.get("updateMetadata.js"))
);
definition.setTriggerOperation(TriggerOperation.CREATE);
definition.setTriggerType(TriggerType.POST);

CosmosTriggerResponse response = container
    .getScripts()
    .createTrigger(definition);

次のコードは、Java SDK を使用してポストトリガーを呼び出す方法を示しています。

ToDoItem item = new ToDoItem();
item.category = "Personal";
item.name = "Doctor";
item.description = "Make appointment for check up";
item.isComplete = true;
    
CosmosItemRequestOptions options = new CosmosItemRequestOptions();
options.setPostTriggerInclude(
    Arrays.asList("postUpdateMetadata")
);

CosmosItemResponse<ToDoItem> response = container.createItem(item, options);

次のコードは、JavaScript SDK を使用してポストトリガーを登録する方法を示しています。

const container = client.database("myDatabase").container("myContainer");
const triggerId = "trgPostUpdateMetadata";
await container.scripts.triggers.create({
    id: triggerId,
    body: require(`../js/${triggerId}`),
    triggerOperation: "create",
    triggerType: "post"
});

次のコードは、JavaScript SDK を使用してポストトリガーを呼び出す方法を示しています。

const item = {
    name: "artist_profile_1023",
    artist: "The Band",
    albums: ["Hellujah", "Rotators", "Spinning Top"]
};
const container = client.database("myDatabase").container("myContainer");
const triggerId = "trgPostUpdateMetadata";
await container.items.create(item, {postTriggerInclude: [triggerId]});

次のコードは、Python SDK を使用してポストトリガーを登録する方法を示しています。

import azure.cosmos.cosmos_client as cosmos_client
from azure.cosmos import documents

url = "your_cosmos_db_account_URI"
key = "your_cosmos_db_account_key"
database_name = 'your_cosmos_db_database_name'
container_name = 'your_cosmos_db_container_name'

with open('../js/trgPostValidateToDoItemTimestamp.js') as file:
    file_contents = file.read()

trigger_definition = {
    'id': 'trgPostValidateToDoItemTimestamp',
    'serverScript': file_contents,
    'triggerType': documents.TriggerType.Post,
    'triggerOperation': documents.TriggerOperation.All
}
client = cosmos_client.CosmosClient(url, key)
database = client.get_database_client(database_name)
container = database.get_container_client(container_name)
trigger = container.scripts.create_trigger(trigger_definition)

次のコードは、Python SDK を使用してポストトリガーを呼び出す方法を示しています。

item = {'category': 'Personal', 'name': 'Groceries',
        'description': 'Pick up strawberries', 'isComplete': False}
container.create_item(item, pre_trigger_include='trgPreValidateToDoItemTimestamp')

ユーザー定義関数を操作する方法

次の例は、Azure Cosmos DB SDK を使用して UDF を登録する方法を示しています。 udfTax.js として保存されているこの例のソースについては、「ユーザー定義関数を記述する方法」を参照してください。

次のコードは、.NET SDK v2 を使用してユーザー定義関数を登録する方法を示しています。

string udfId = "Tax";
var udfTax = new UserDefinedFunction
{
    Id = udfId,
    Body = File.ReadAllText($@"..\js\{udfId}.js")
};

Uri containerUri = UriFactory.CreateDocumentCollectionUri("myDatabase", "myContainer");
await client.CreateUserDefinedFunctionAsync(containerUri, udfTax);

次のコードは、.NET SDK v2 を使用してユーザー定義関数を呼び出す方法を示しています。

Uri containerUri = UriFactory.CreateDocumentCollectionUri("myDatabase", "myContainer");
var results = client.CreateDocumentQuery<dynamic>(containerUri, "SELECT * FROM Incomes t WHERE udf.Tax(t.income) > 20000"));

foreach (var result in results)
{
    //iterate over results
}

次のコードは、.NET SDK v3 を使用してユーザー定義関数を登録する方法を示しています。

await client.GetContainer("database", "container").Scripts.CreateUserDefinedFunctionAsync(new UserDefinedFunctionProperties
{
    Id = "Tax",
    Body = File.ReadAllText(@"..\js\Tax.js")
});

次のコードは、.NET SDK v3 を使用してユーザー定義関数を呼び出す方法を示しています。

var iterator = client.GetContainer("database", "container").GetItemQueryIterator<dynamic>("SELECT * FROM Incomes t WHERE udf.Tax(t.income) > 20000");
while (iterator.HasMoreResults)
{
    var results = await iterator.ReadNextAsync();
    foreach (var result in results)
    {
        //iterate over results
    }
}

次のコードは、Java SDK を使用してユーザー定義関数を登録する方法を示しています。

CosmosUserDefinedFunctionProperties definition = new CosmosUserDefinedFunctionProperties(
    "udfTax",
    Files.readString(Paths.get("tax.js"))
);

CosmosUserDefinedFunctionResponse response = container
    .getScripts()
    .createUserDefinedFunction(definition);

次のコードは、Java SDK を使用してユーザー定義関数を呼び出す方法を示しています。

CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();

CosmosPagedIterable<ToDoItem> iterable = container.queryItems(
    "SELECT t.cost, udf.udfTax(t.cost) AS costWithTax FROM t", 
    options, 
    ToDoItem.class);

次のコードは、JavaScript SDK を使用してユーザー定義関数を登録する方法を示しています。

const container = client.database("myDatabase").container("myContainer");
const udfId = "Tax";
await container.userDefinedFunctions.create({
    id: udfId,
    body: require(`../js/${udfId}`)

次のコードは、JavaScript SDK を使用してユーザー定義関数を呼び出す方法を示しています。

const container = client.database("myDatabase").container("myContainer");
const sql = "SELECT * FROM Incomes t WHERE udf.Tax(t.income) > 20000";
const {result} = await container.items.query(sql).toArray();

次のコードは、Python SDK を使用してユーザー定義関数を登録する方法を示しています。

import azure.cosmos.cosmos_client as cosmos_client

url = "your_cosmos_db_account_URI"
key = "your_cosmos_db_account_key"
database_name = 'your_cosmos_db_database_name'
container_name = 'your_cosmos_db_container_name'

with open('../js/udfTax.js') as file:
    file_contents = file.read()
udf_definition = {
    'id': 'Tax',
    'serverScript': file_contents,
}
client = cosmos_client.CosmosClient(url, key)
database = client.get_database_client(database_name)
container = database.get_container_client(container_name)
udf = container.scripts.create_user_defined_function(udf_definition)

次のコードは、Python SDK を使用してユーザー定義関数を呼び出す方法を示しています。

results = list(container.query_items(
    'query': 'SELECT * FROM Incomes t WHERE udf.Tax(t.income) > 20000'))

次の方法で共有

Azure Cosmos DB でストアド プロシージャ、トリガー、およびユーザー定義関数を登録および使用する方法

ストアド プロシージャの実行方法

プリトリガーを実行する方法

ポストトリガーの実行方法

ユーザー定義関数を操作する方法

次のステップ

フィードバック

その他のリソース

Azure Cosmos DB でストアドプロシージャ、トリガー、およびユーザー定義関数を登録および使用する方法

ストアドプロシージャの実行方法