Azure Cosmos DB에서 저장 프로시저, 트리거 및 사용자 정의 함수를 등록하고 사용하는 방법

아티클
08/15/2024

적용 대상: NoSQL

Azure Cosmos DB의 API for NoSQL은 저장 프로시저, 트리거 및 JavaScript로 작성된 UDF(사용자 정의 함수)를 등록하고 호출하도록 지원합니다. 하나 이상의 저장 프로시저, 트리거 또는 사용자 정의 함수를 정의한 후 데이터 탐색기를 사용하여 Azure Portal에서 로드하고 볼 수 있습니다.

.NET v2(레거시), .NET v3 , Java, JavaScript 또는 Python SDK를 비롯한 여러 플랫폼에서 NoSQL SDK용 API를 사용하여 이러한 작업을 수행할 수 있습니다. 이전에 이러한 SDK 중 하나를 사용해 본 적이 없는 경우 적절한 SDK에 대한 빠른 시작 문서를 참조하세요.

SDK	시작하기
.NET v3	빠른 시작: .NET용 Azure Cosmos DB for NoSQL 클라이언트 라이브러리
Java	빠른 시작: Azure Cosmos DB for NoSQL 데이터를 관리하는 Java 앱 빌드
JavaScript	빠른 시작: Node.js 위한 NoSQL용 Azure Cosmos DB 클라이언트 라이브러리
Python	빠른 시작: Python용 Azure Cosmos DB for NoSQL 클라이언트 라이브러리

Important

다음 코드 샘플에서는 이미 client 변수와 container 변수가 있다고 가정합니다. 이러한 변수를 만들어야 하는 경우 플랫폼에 적합한 빠른 시작을 참조하세요.

저장 프로시저를 실행하는 방법

저장 프로시저는 JavaScript를 사용하여 작성됩니다. Azure Cosmos DB 컨테이너 내에서 항목을 만들고, 업데이트하고, 읽고, 쿼리하고, 삭제할 수 있습니다. 자세한 내용은 저장 프로시저를 작성하는 방법을 참조 하세요.

다음 예제에서는 Azure Cosmos DB SDK를 사용하여 저장 프로시저를 등록하고 호출하는 방법을 보여줍니다. spCreateToDoItem.js 저장되는 이 저장 프로시저의 원본은 저장 프로시저를 사용하여 항목 만들기를 참조하세요.

참고 항목

분할된 컨테이너의 경우 저장 프로시저를 실행할 때 요청 옵션에 파티션 키 값을 제공해야 합니다. 저장 프로시저의 범위는 항상 파티션 키로 지정됩니다. 다른 파티션 키 값을 가진 항목은 저장 프로시저에 표시되지 않습니다. 이 원칙은 트리거에도 적용됩니다.

다음 예제는 .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 저장되는 이 프리트리거 예제의 원본은 Pretriggers를 참조하세요.

개체에서 트리거 이름을 지정하고 전달하여 PreTriggerInclude 작업을 실행하면 개체에 List 프리트리거가 RequestOptions 전달됩니다.

참고 항목

트리거 이름이 a List로 전달되더라도 작업당 하나의 트리거만 실행할 수 있습니다.

다음 코드에서는 .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를 사용하여 사용자 정의 함수를 등록하는 방법을 보여줍니다. 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에서 저장 프로시저, 트리거 및 사용자 정의 함수를 작성하고 사용하는 개념 및 방법을 알아봅니다.

다음을 통해 공유