Sub-document API in Couchbase Server 4.5 with the .NET SDK

이 블로그 게시물은 제프 모리스의 이전 블로그 게시물 하위 문서 API가 아직 개발자 프리뷰 버전일 때 다루었던 내용입니다. 해당 릴리스 이후 API에 몇 가지 변경 사항이 있었습니다.

함께 카우치베이스 서버 4.5 및 .NET SDK 2.3.x를 사용하여 이제 하위 문서 기능을 사용할 수 있습니다.

이전 Couchbase 릴리스에서는 모든 문서 변경이 전체 문서와 관련된 원자적 변경이었습니다. 단일 필드만 변경한 다음 업데이트를 수행하려는 경우 새 수정본에 의해 Couchbase 서버의 전체 문서가 복사됩니다. 문제는 문서가 크거나 네트워크가 느린 경우(또는 둘 다) 수정되지 않은 데이터를 전송하는 데 많은 리소스가 낭비된다는 것입니다. 더 나은 성능의 솔루션은 문서의 일부분 또는 변경된 값만 전송하는 것입니다. 기본적으로 하위 문서 API를 사용하면 문서의 요소를 업데이트하거나 요소를 삭제할 때 변경할 조각의 경로만 유선으로 전송되고 문서의 해당 부분만 수정됩니다.

API에서 지원하는 작업에는 개별 중첩 요소의 변이(일명 sub-문서)를 배열 및 사전 수정으로 변환할 수 있습니다. 카운터 연산도 지원되며, 임베디드 JSON 조각에 대한 검색 연산도 지원됩니다.

API는 다음을 통해 노출됩니다. 유창한 인터페이스를 사용하면 여러 연산을 추가한 다음 문서에 대해 원자적으로 실행할 수 있습니다. 변경 연산을 위한 빌더와 읽기 또는 '조회'(주어진 경로에 요소가 존재하는지 확인할 수도 있음)를 위한 빌더의 두 가지 '빌더'가 있습니다.

필수 구성 요소: Couchbase Server 4.5

아래 예시를 따르려면 다음을 다운로드하여 설치해야 합니다. 카우치베이스 서버 4.5. 이전에 Couchbase Server를 설치한 적이 없다면 다음 동영상에서 확인할 수 있습니다. Windows에 Couchbase Server를 설치하는 방법. 어떤 OS를 사용하든 정말 쉽습니다.

하위 문서 API 개요

다음 예제에서는 ID가 'puppy'인 문서를 사용하며 다음과 같이 시작됩니다:

  {
  "type": "dog",
  "breed": "Pitbull/Chihuahua",
  "name": "Puppy",
  "toys": [
    "squeaker",
    "ball",
    "shoe"
  ],
  "owner": {
    "type": "servant",
    "name": "Don Knotts",
    "age": 63
  },
  "attributes": {
    "fleas": true,
    "color": "white",
    "eyeColor": "brown",
    "age": 5,
    "dirty": true,
    "sex": "female"
  }
}

{

"type": "dog",

"breed": "핏불/치와와",

"name": "강아지",

"장난감": [

"squeaker",

"ball",

"shoe"

"소유자": {

"type": "servant",

"name": "돈 노트",

"age": 63

"속성": {

"fleas": true,

"color": "white",

"eyeColor": "갈색",

"age": 5,

"더러운": true,

"sex": "여성"

}

모든 예제는 깃허브에서 확인할 수 있습니다. 를 사용하여 프로젝트를 복제하고 API를 사용해 볼 수 있습니다.

MutateInBuilder 및 룩업인빌더

하위 문서 API는 문서에서 여러 작업을 연결하기 위해 유창한 인터페이스를 통해 빌더 패턴을 활용하는 두 가지 새로운 유형을 제공합니다. 두 개체 모두 MutateIn 또는 룩업인 에 카우치베이스버킷 객체를 생성하고 작업 중인 문서의 키를 전달합니다:

//Initialize the cluster helper with the default settings - i.e. localhost
ClusterHelper.Initialize();
var bucket = ClusterHelper.GetBucket("default");

//create a mutation builder for the document "thekey"
var mutate = bucket.MutateIn("thekey");

//create a lookup builder for the document "thekey2"
var lookup = bucket.LookupIn("thekey2");

ClusterHelper.Close();

//기본 설정으로 클러스터 도우미를 초기화합니다(예: localhost).

클러스터 도우미.초기화();

var 버킷 = 클러스터 도우미.GetBucket("default");

//문서 "thekey"에 대한 변이 빌더를 생성합니다.

var 돌연변이 = 버킷.MutateIn("thekey");

// "thekey2" 문서에 대한 조회 빌더를 만듭니다.

var 조회 = 버킷.룩업인("thekey2");

클러스터 도우미.닫기();

빌더 객체가 있으면 예를 들어 문서에 대해 실행할 여러 작업을 체인으로 연결할 수 있습니다:

var builder = bucket.LookupIn(id).
    Get("type").
    Get("name").
    Get("owner").
    Exists("notfound");

var 빌더 = 버킷.룩업인(id).

Get("type").

Get("name").

Get("소유자").

존재("notfound");

그런 다음 모든 작업을 한 번에 서버로 전송할 수 있습니다:

var fragment = builder.Execute();

1	var 조각 = 빌더.실행();

OpStatus와 경로를 사용하여 한 작업의 결과를 확인할 수 있습니다. 이 예제에서는 경로 "type":

if (fragment.OpStatus("type") == ResponseStatus.Success)
{
    string format = "Path='{0}' Value='{1}'";
    Console.WriteLine(format, "type", fragment.Content("type"));
}

만약 (조각.OpStatus("type") == 응답 상태.성공)

{

문자열 형식 = "Path='{0}' Value='{1}'";

콘솔.WriteLine(형식, "type", 조각.콘텐츠("type"));

}

다음은 몇 가지 방법과 필드에 대한 설명입니다. IDocumentFragment 인터페이스.

이름

설명

콘텐츠(...)

지정된 경로 또는 인덱스의 콘텐츠를 가져옵니다.

존재(...)

지정된 경로 또는 인덱스에 대한 결과가 있는 경우 true를 반환합니다.

Count()

빌더가 유지 관리하는 현재 작업의 개수입니다.

OpStatus(...)

그리고 응답 상태 인덱스 또는 경로에서 작업을 수행합니다.

상태

그리고 응답 상태 를 사용하여 전체 다중 작업을 수행합니다.

성공

전체 다중 작업이 성공하면 참입니다.

이러한 프로퍼티 또는 메서드 외에도 다음에서 상속된 다른 모든 프로퍼티가 있습니다. 작업 결과 (키/값 연산의 표준 응답): 업서트, 제거, 바꾸기 등.

오류 처리

여러 개의 돌연변이중 하나가 실패하면 전체 다중 작업 요청이 실패합니다. 이렇게 하면 단일 문서 내에서 변경을 수행할 때 트랜잭션 '전부 아니면 전무' 시맨틱을 사용할 수 있습니다.

여러 개의 조회를 사용하면 서버가 요청된 만큼의 항목을 반환하려고 시도하면서 일부 작업은 성공하고 일부는 실패할 수 있습니다.

작업이 실패한 경우에는상태 속성에는 다음과 같은 최상위 오류 응답이 포함됩니다. 하위 문서 다중 경로 실패. 이는 구체적인 오류를 파악하기 위해 작업 결과를 더 자세히 조사해야 한다는 표시입니다. 이 작업을 반복하여 수행할 수 있습니다. OpStatus 메서드를 호출하고 인덱스 또는 경로를 전달합니다:

var builder = bucket.LookupIn(id).
    Get("type").
    Get("somepaththatdoesntexist").
    Get("owner");

var fragment = builder.Execute();
Console.WriteLine("Generic error: {0}{1}Specific Error: {2}",
    fragment.Status, Environment.NewLine, fragment.OpStatus(1));

Console.WriteLine("Generic error: {0}{1}Specific Error: {2}",
   fragment.Status, Environment.NewLine, fragment.OpStatus("somepaththatdoesntexist"));

var 빌더 = 버킷.룩업인(id).

Get("type").

Get("일부 경로가 존재하지 않음").

Get("소유자");

var 조각 = 빌더.실행();

콘솔.WriteLine("일반 오류입니다: {0}{1}특정 오류입니다: {2}",

조각.상태, 환경.뉴라인, 조각.OpStatus(1));

콘솔.WriteLine("일반 오류입니다: {0}{1}특정 오류입니다: {2}",

조각.상태, 환경.뉴라인, 조각.OpStatus("일부 경로가 존재하지 않음"));

이 경우 문서 내에 "일부 경로가 존재하지 않는 경로"가 존재하지 않으므로 반환된 특정 오류는 다음과 같습니다. 하위 문서 경로를 찾을 수 없음. 빌더 유형과 오류 조건에 따라 다양한 조합의 오류가 발생할 수 있습니다.

룩업인빌더 예제

그리고 룩업인빌더 유형은 경로별로 값을 가져오는 것과 지정된 경로에 값이 있는지 확인하는 두 가지 작업을 지원합니다.

Get:

조회해 보겠습니다. 소유자 조각을 반환합니다. 이 메서드에 경로 매개 변수로 "owner"를 전달하면...

public static void GetExample(IBucket bucket, string path, string id)
{
    var builder = bucket.LookupIn(id).
        Get(path).
        Execute();

    var fragment = builder.Content(path);
    Console.WriteLine(fragment);
}

public 정적 void GetExample(IBucket 버킷, 문자열 경로, 문자열 id)

{

var 빌더 = 버킷.룩업인(id).

Get(경로).

실행();

var 조각 = 빌더.콘텐츠(경로);

콘솔.WriteLine(조각);

}

...콘솔에 출력되는 내용은 다음과 같습니다:

{
    "type": "servant",
    "name": "Don Knotts",
    "age": 63
}

{

"type": "servant",

"name": "돈 노트",

"age": 63

}

존재합니다:

경로가 존재하는지 확인할 수도 있습니다. 이 메서드의 경로로 "owner"를 전달하면...

public static void ExistsExample(IBucket bucket, string path, string id)
{
    var builder = bucket.LookupIn(id).
        Exists(path).
        Execute();

    var found = builder.Content(path);
    Console.WriteLine(found);
}

public 정적 void 존재예시(IBucket 버킷, 문자열 경로, 문자열 id)

{

var 빌더 = 버킷.룩업인(id).

존재(경로).

실행();

var 발견 = 빌더.콘텐츠(경로);

콘솔.WriteLine(발견);

}

...출력은 다음과 같습니다. true경로가 소유자 가 문서 내에 실제로 존재합니다.

뮤테이트인빌더

MutateInBuilder는 스칼라 값, 딕셔너리 및 배열의 변형을 지원하는 다양한 메서드와 원자 카운터 연산을 지원합니다.

삽입합니다:

삽입은 사전에 값을 추가하며, 선택적으로 포함 요소(사전 자체)를 추가할 수 있습니다.

public static void InsertExample(IBucket bucket, string id, string path, string value)
{
    var fragment = bucket.MutateIn(id).
        Insert(path, value, true).  // false is the default
        Execute();

    var status = fragment.OpStatus(path);
    Console.WriteLine(status);
}

public 정적 void 삽입 예제(IBucket 버킷, 문자열 id, 문자열 경로, 문자열 값)

{

var 조각 = 버킷.MutateIn(id).

삽입(경로, 값, true). // false가 기본값입니다.

실행();

var 상태 = 조각.OpStatus(경로);

콘솔.WriteLine(상태);

}

위의 메서드를 이렇게 호출했다면

InsertExample(bucket, id,"attributes.hairLength", "short");

1	삽입 예제(버킷, id,"attributes.hairLength", "short");

이제 문서의 속성 사전은 다음과 같이 표시됩니다:

...
"attributes":
{
    "fleas": true,
    "color": "white",
    "eyeColor": "brown",
    "age": 5,
    "dirty": true,
    "sex": "female",
    "hairLength": "short"
}
...

...

"속성":

{

"fleas": true,

"color": "white",

"eyeColor": "갈색",

"age": 5,

"더러운": true,

"sex": "여성",

"hairLength": "short"

}

...

참고 삽입 메서드에는 선택적 부울 매개변수인 createParents. 기본적으로 거짓입니다. true이면 하위 문서 API가 필드가 존재하는 데 필요한 경로를 만듭니다. false인 경우 하위 문서 API는 필드의 부모가 이미 존재하는 경우에만 필드를 만듭니다. 위의 예에서 속성 필드가 이미 존재했습니다.

다음 예제에서는 상위 필드(새로운 속성)를 생성할 수 있습니다.

InsertExample(bucket, id, "anewattribute.withakey", "somevalue");

1	삽입 예제(버킷, id, "anewattribute.withakey", "일부값");

그러면 다음과 같은 새 속성이 생성됩니다. 새로운 속성 라는 단일 키를 문서에 추가하고 withakey 값으로 일부값.

...
"anewattribute":
{
    "withakey": "somevalue"
}
...

...

"anewattribute":

{

"withakey": "일부값"

}

...

이제 우리가 통과했다면 false 에 대한 createParents 로 설정되어 있고 부모 속성이 존재하지 않으면 다중 변이가 실패하고 최상위 응답 상태는 하위 문서 다중 경로 실패 구체적인 오류는 다음과 같습니다. 하위 문서 경로를 찾을 수 없음.

Upsert

업서트는 기존 사전 항목을 추가하거나 바꿉니다. 사용법은 삽입 메서드 이름이 Upsert.

제거

제거 는 지정된 경로에서 요소를 제거합니다.

public static void RemoveExample(IBucket bucket, string id, string path)
{
    var fragment = bucket.MutateIn(id).
        Remove(path).
        Execute();

    var status = fragment.OpStatus(path);
    Console.WriteLine(status);
}

public 정적 void 제거 예제(IBucket 버킷, 문자열 id, 문자열 경로)

{

var 조각 = 버킷.MutateIn(id).

제거(경로).

실행();

var 상태 = 조각.OpStatus(경로);

콘솔.WriteLine(상태);

}

이 메서드를 호출하면

RemoveExample(bucket, id, "owner.name");

1	제거 예제(버킷, id, "owner.name");

나중에 문서가 어떻게 표시되는지는 다음과 같습니다:

...
"owner":
{
    "type": "servant",
    "age": 63
},
...

...

"소유자":

{

"type": "servant",

"age": 63

...

교체

바꾸기는 지정된 경로에서 요소의 값을 바꾸며, 경로가 존재하지 않으면 실패합니다:

public static void ReplaceExample(IBucket bucket, string id, string path, object value)
{
    var fragment = bucket.MutateIn(id).
        Replace(path, value).
        Execute();

    var status = fragment.OpStatus(path);
    Console.WriteLine(status);
}

public 정적 void ReplaceExample(IBucket 버킷, 문자열 id, 문자열 경로, 객체 값)

{

var 조각 = 버킷.MutateIn(id).

교체(경로, 값).

실행();

var 상태 = 조각.OpStatus(경로);

콘솔.WriteLine(상태);

}

이 메서드를 호출한 후

ReplaceExample(bucket, id, "owner", new { CatLover=true, CatName="celia"});

1	ReplaceExample(버킷, id, "소유자", new { CatLover=true, 고양이 이름="celia"});

이제 문서의 '소유자' 값이 달라집니다:

...
"owner":
{
    "catLover": true,
    "catName": "celia"
},
...

...

"소유자":

{

"catLover": true,

"catName": "celia"

...

ArrayAppend

ArrayAppend는 배열의 끝에 값을 추가하며, 부모 요소가 없는 경우 선택적으로 부모 요소(배열 요소 자체)를 추가합니다.

public static void ArrayAppendExample(IBucket bucket, string id, string path, object value)
{
    var fragment = bucket.MutateIn(id).
        ArrayAppend(path, value, false).
        Execute();

    var status = fragment.OpStatus(path);
    Console.WriteLine(status);
}

public 정적 void ArrayAppendExample(IBucket 버킷, 문자열 id, 문자열 경로, 객체 값)

{

var 조각 = 버킷.MutateIn(id).

ArrayAppend(경로, 값, false).

실행();

var 상태 = 조각.OpStatus(경로);

콘솔.WriteLine(상태);

}

"장난감" 경로로 이 방법을 사용한 후...

ArrayAppendExample(bucket, id, "toys", "slipper");

1	ArrayAppendExample(버킷, id, "장난감", "slipper");

... 장난감 배열은 문서의 마지막 서수에 "slipper" 값을 갖습니다:

...
"toys":
[
    "squeaker",
    "ball",
    "shoe",
    "slipper"
],
...

...

"장난감":

[

"squeaker",

"ball",

"shoe",

"slipper"

...

ArrayPrepend

ArrayPrepend는 ArrayAppend와 동일한 방식으로 작동하지만, 값을 추가한다는 점을 제외하면 앞 배열의

public static void ArrayAppendExample(IBucket bucket, string id, string path, object value)
{
    var fragment = bucket.MutateIn(id).
        ArrayAppend(path, value, false).
        Execute();

    var status = fragment.OpStatus(path);
    Console.WriteLine(status);
}

public 정적 void ArrayAppendExample(IBucket 버킷, 문자열 id, 문자열 경로, 객체 값)

{

var 조각 = 버킷.MutateIn(id).

ArrayAppend(경로, 값, false).

실행();

var 상태 = 조각.OpStatus(경로);

콘솔.WriteLine(상태);

}

"toys" 경로로 해당 메서드를 호출하면...

ArrayAppendExample(bucket, id, "toys", "slipper");

1	ArrayAppendExample(버킷, id, "장난감", "slipper");

그리고 장난감 배열에 이제 "slipper" 값이 있습니다. 먼저 서수입니다:

...
"toys":
[
    "slipper",
    "squeaker",
    "ball",
    "shoe"
],
...

...

"장난감":

[

"slipper",

"squeaker",

"ball",

"shoe"

...

ArrayInsert

ArrayPrepend는 값을 처음에, ArrayAppend는 끝에 넣습니다. 끝을 마무리하기 위해 ArrayInsert를 사용하여 그 사이 어딘가에(주어진 인덱스에) 값을 넣을 수 있습니다.

public static void ArrayInsertExample(IBucket bucket, string id, string path, object value)
{
    var fragment = bucket.MutateIn(id).
        ArrayInsert(path, value).
        Execute();

    var status = fragment.OpStatus(path);
    Console.WriteLine(status);
}

public 정적 void ArrayInsertExample(IBucket 버킷, 문자열 id, 문자열 경로, 객체 값)

{

var 조각 = 버킷.MutateIn(id).

ArrayInsert(경로, 값).

실행();

var 상태 = 조각.OpStatus(경로);

콘솔.WriteLine(상태);

}

그리고 그 메서드를 "toys[2]"로 호출합니다...

ArrayInsertExample(bucket, id, "toys[2]", "slipper");

1	ArrayInsertExample(버킷, id, "장난감[2]", "slipper");

그리고 장난감 배열은 이제 세 번째 서수(인덱스 2)에 "slipper" 값을 갖습니다:

"toys":
[
    "squeaker",
    "ball",
    "slipper",
    "shoe"
 ],

"장난감":

[

"squeaker",

"ball",

"slipper",

"shoe"

ArrayAddUnique

ArrayAddUnique는 배열에 값을 삽입하지만 해당 값이 이미 존재하는 경우(즉, 값이 배열 내에서 고유해야 함) 실패합니다.

public static void ArrayAddUniqueExample(IBucket bucket, string id, string path, object value)
{
    var fragment = bucket.MutateIn(id).
        ArrayAddUnique(path, value).
        Execute();

    var status = fragment.OpStatus(path);
    Console.WriteLine(status);
}

public 정적 void ArrayAddUniqueExample(IBucket 버킷, 문자열 id, 문자열 경로, 객체 값)

{

var 조각 = 버킷.MutateIn(id).

ArrayAddUnique(경로, 값).

실행();

var 상태 = 조각.OpStatus(경로);

콘솔.WriteLine(상태);

}

"신발"이라고 부르면...

ArrayAddUniqueExample(bucket, id, "toys", "shoe");

1	ArrayAddUniqueExample(버킷, id, "장난감", "shoe");

... "shoe" 값이 이미 원본 문서의 장난감 배열을 사용하면 상태 하위 문서 경로 존재.

이 메서드에서는 문자열, 숫자, 참, 거짓 또는 null의 특수 값과 같은 JSON 기본 요소만 삽입할 수 있습니다. 각 JSON 객체로 내려가서 요소를 항목별로 비교하지 않고는 고유성을 비교할 수 있는 방법이 없습니다.

카운터

기존 값에 지정된 델타(변경)를 추가하여 요소가 존재하지 않는 경우 요소를 만듭니다. 값과 델타는 모두 0으로 기본 설정됩니다. 델타가 음수인 경우 요소의 값은 지정된 델타만큼 감소합니다.

다음을 사용하는 메서드를 만들겠습니다. 카운터:

public static void CounterExample(IBucket bucket, string id, string path, long delta)
{
    var fragment = bucket.MutateIn(id).
        Counter(path, delta).
        Execute();

    var status = fragment.OpStatus(path);
    Console.WriteLine(status);
}

public 정적 void 카운터 예제(IBucket 버킷, 문자열 id, 문자열 경로, long 델타)

{

var 조각 = 버킷.MutateIn(id).

카운터(경로, 델타).

실행();

var 상태 = 조각.OpStatus(경로);

콘솔.WriteLine(상태);

}

그런 다음 양수 1과 음수 1을 '델타'로 사용하여 메서드를 두 번 호출합니다:

CounterExample(bucket, id, "likes", 1);
CounterExample(bucket, id, "likes", -1);

1 2	카운터 예제(버킷, id, "좋아요", 1); 카운터 예제(버킷, id, "좋아요", -1);

첫 번째 호출 후에는 요소가 존재하지 않으므로 요소가 생성된 다음 하나(1)로 설정됩니다. 이제 문서가 다음과 같이 표시됩니다:

...
    ],
    "likes": 1
}

...

"좋아요": 1

}

두 번째 호출은 음수(-1)를 전달하므로 다음 카운터는 좋아요 는 0으로 감소합니다. 이제 JSON 문서는 다음과 같이 표시됩니다:

...
    ],
    "likes": 0
}

...

"좋아요": 0

}

결론

개발자 프리뷰 블로그 게시물 이후 Couchbase .NET SDK는 버전 2.3.2로 업데이트되었습니다(이 블로그 게시물 작성 시점 기준). 그 동안의 작업 내용을 확인하려면 버전 2.3.2의 릴리스 노트.

v2.3.x를 다운로드하는 방법

바이너리 다운로드 저장소(2.3.3이 최신 릴리스)에서 .NET SDK 2.3.x용을 다운로드할 수 있습니다.
다음에서 NuGet의 최신 SDK.
그리고 소스 코드는 깃허브에서 확인할 수 있습니다.

최종 참고 사항

하위 문서 API는 문서와의 상호작용을 더욱 세분화할 수 있는 기능을 제공합니다. 필요한 부분만 수정하고 검색할 수 있습니다.

아래에 댓글을 남겨주세요, 트위터에서 저와 대화하기를 참조하거나 질문이나 의견이 있으면 저에게 이메일(matthew.groves AT couchbase DOT com)로 문의하세요.

매튜 그로브스

Platform

Self-Managed

Services

Capabilities

Why Couchbase?

Migrate to Capella

By Use Case

By Industry

By Application Need

Popular Docs

By Developer Role

Quickstart

Resource Center

About

Partnerships

Our Services

Partners: Register a Deal

Ready to register a deal with Couchbase?

Marriott

모든 게시물

.NET SDK가 포함된 Couchbase Server 4.5의 하위 문서 API(재검토)

필수 구성 요소: Couchbase Server 4.5

하위 문서 API 개요

MutateInBuilder 및 룩업인빌더

오류 처리

룩업인빌더 예제

Get:

존재합니다:

뮤테이트인빌더

삽입합니다:

Upsert

제거

교체

ArrayAppend

ArrayPrepend

ArrayInsert

ArrayAddUnique

카운터

결론

v2.3.x를 다운로드하는 방법

최종 참고 사항

작성자

게시자 매튜 그로브스

댓글 남기기 응답 취소