테이블 및 엔터티 쿼리
Table service의 테이블 및 엔터티를 쿼리하기 위해서는 요청 URI를 주의해서 생성해야 합니다. 다음 섹션에서는 쿼리 옵션에 대해 설명하고 몇 가지 공통적인 시나리오를 보여줍니다.
기본 쿼리 구문
지정된 스토리지 계정의 모든 테이블을 반환하려면 테이블 쿼리 작업에 설명된 대로 테이블 리소스에 대한 작업을 수행 GET합니다 . 테이블 리소스를 나열하는 기본 URI는 다음과 같습니다.
https://myaccount.table.core.windows.net/Tables
단일 명명된 테이블을 반환하려면 다음과 같이 해당 테이블을 지정합니다.
https://myaccount.table.core.windows.net/Tables('MyTable')
테이블에 있는 모든 엔터티를 반환하려면 테이블 리소스 없이 URI에 테이블 이름을 지정합니다.
https://myaccount.table.core.windows.net/MyTable()
쿼리 결과는 PartitionKey 및 RowKey 순서로 정렬됩니다. 다른 방식으로의 결과 순서 지정은 현재까지 지원되지 않습니다.
다음 지원되는 쿼리 옵션 섹션의 설명에 따라 추가 옵션을 지정해서 반환되는 테이블 또는 엔터티 집합을 제한할 수 있습니다.
참고
쿼리가 최대 엔터티 수를 초과하거나, 제한 시간 간격을 초과하거나, 분할 경계를 넘을 경우 단일 요청에 대해 반환되는 엔터티 수가 제한될 수 있습니다. 자세한 내용은 쿼리 시간 제한 및 페이지 매김을 참조하세요.
지원되는 쿼리 옵션
Table Service는 OData 프로토콜 사양을 준수하는 다음 쿼리 옵션을 지원합니다. 이러한 옵션을 사용하여 쿼리로 반환되는 테이블, 엔터티 또는 엔터티 속성 집합을 제한할 수 있습니다.
| 시스템 쿼리 옵션 | Description |
|---|---|
$filter |
지정된 필터를 충족하는 테이블 또는 엔터티만 반환합니다.$filter 문자열 내에서는 최대 15개까지만 불연속 비교가 허용됩니다. |
$top |
집합에서 최상위 n개 테이블 또는 엔터티만 반환합니다. |
$select |
집합에서 원하는 엔터티 속성을 반환합니다. 이 쿼리 옵션은 2011-08-18 버전 이상을 사용하는 요청에만 지원됩니다. 자세한 내용은 Table Service에 대해 LINQ 쿼리 작성을 참조하세요. |
참고
기본 최대값 또는 지정된 최대 결과 수를 초과하는 요청은 페이지 매김을 수행하기 위한 연속 토큰을 반환합니다. 연속 토큰을 포함하는 후속 요청을 만들 때 요청에 원래 URI를 전달해야 합니다. 예를 들어 원래 요청의 일부로 , $select또는 $top 쿼리 옵션을 지정$filter한 경우 후속 요청에 해당 옵션을 포함해야 합니다. 그렇지 않으면 후속 요청이 예기치 않은 결과를 반환할 수 있습니다. 자세한 내용은 쿼리 시간 제한 및 페이지 매김 을 참조하세요.
$top 결과가 페이지를 매긴 경우 쿼리 옵션은 전체 응답 집합의 최대 결과 수가 아니라 페이지당 최대 결과 수를 지정합니다.
OData에 정의된 추가 쿼리 옵션은 테이블 서비스에서 지원되지 않습니다.
지원되는 비교 연산자
$filter 절 내에서 비교 연산자를 사용하여 쿼리 결과를 필터링할 조건을 지정할 수 있습니다.
모든 속성 유형에 대해 다음과 같은 비교 연산자가 지원됩니다.
| 연산자 | URI 식 |
|---|---|
Equal |
eq |
GreaterThan |
gt |
GreaterThanOrEqual |
ge |
LessThan |
lt |
LessThanOrEqual |
le |
NotEqual |
ne |
또한 부울 속성에 대해 다음과 같은 연산자가 지원됩니다.
| 연산자 | URI 식 |
|---|---|
And |
and |
Not |
not |
Or |
or |
필터 구문에 대한 자세한 내용은 OData 프로토콜 사양을 참조하세요.
쿼리 문자열 인코딩
쿼리 문자열에 사용할 경우에는 다음 문자를 인코딩해야 합니다.
- 슬래시(/)
- 물음표(?)
- 콜론(:)
- @ 기호(at 기호)
- 앰퍼샌드 (&)
- 등호(=)
- 더하기 기호(+)
- 쉼표(,)
- 달러 기호($)
작은따옴표(')
쿼리 문자열의 작은따옴표는 연속된 두 개의 작은따옴표('')로 표현되어야 합니다. 예를 들어 "o'clock"은 다음과 같습니다.
o''clock
예제 쿼리 식
다음 예제에서는 REST 구문을 사용해서 몇 가지 일반적인 엔터티 쿼리에 대해 요청 URI를 생성하는 방법을 보여줍니다. LINQ 구문을 사용해서 동일한 쿼리를 작성할 수 있습니다. 자세한 내용은 Table Service에 대해 LINQ 쿼리 작성을 참조하세요.
$top 및 $filter 옵션 모두 String 형식의 속성으로 필터링하기 위해 설명된 구문을 사용해서 테이블 이름으로 필터링하는 데 사용할 수 있습니다.
상위 n개 엔터티 반환
쿼리에 대해 상위 n개 엔터티를 반환하려면 $top 쿼리 옵션을 지정합니다. 다음 예에서는 Customers라는 테이블에서 상위 10개 엔터티를 반환합니다.
https://myaccount.table.core.windows.net/Customers()?$top=10
PartitionKey 및 RowKey 속성에 대한 필터링
PartitionKey 및 RowKey 속성은 엔터티의 기본 키를 형성하므로 특수 구문을 사용해서 다음과 같이 엔터티를 식별할 수 있습니다.
https://myaccount.table.core.windows.net/Customers(PartitionKey='MyPartition',RowKey='MyRowKey1')
또는 다음 섹션과 같이 $filter 옵션의 일부로 이러한 속성을 지정할 수 있습니다.
키 속성 이름과 상수 값은 대/소문자를 구분합니다.
PartitionKey 및 RowKey 속성 모두 String 형식입니다.
필터 문자열 생성
필터 문자열을 생성할 때는 다음 규칙에 유의하세요.
OData 프로토콜 사양에 정의된 논리 연산자를 사용하여 속성을 값과 비교합니다. 참고로 동적 값에 속성을 비교할 수 있으며 식의 한쪽은 상수여야 합니다.
속성 이름, 연산자 및 상수 값은 URL로 인코딩된 공백으로 구분해야 합니다. URL로 인코딩된 공백은
%20입니다.필터 문자열의 모든 부분은 대/소문자를 구분합니다.
상수 값은 유효한 결과를 반환하는 필터에 대한 속성과 동일한 데이터 형식이어야 합니다. 속성 형식에 대한 자세한 내용은 테이블 서비스 데이터 모델 이해를 참조하세요.
참고
해당 형식이 문자열 형식이라고 가정하기 전에 속성이 명시적으로 형식화되어 있는지 여부를 확인하세요. 속성의 형식이 명시적으로 지정된 경우 엔터티가 반환될 때 해당 형식이 응답 내에 표시됩니다. 속성의 형식이 명시적으로 지정되지 않은 경우에는 String 형식이 되며, 엔터티가 반환될 때 해당 형식이 응답 내에 표시되지 않습니다.
문자열 속성 필터링
문자열 속성으로 필터링할 때는 문자열 상수를 작은 따옴표로 묶습니다.
다음 예에서는 PartitionKey 및 RowKey 속성으로 필터링합니다. 키가 아닌 추가 속성을 쿼리 문자열에 추가할 수도 있습니다.
https://myaccount.table.core.windows.net/Customers()?$filter=PartitionKey%20eq%20'MyPartitionKey'%20and%20RowKey%20eq%20'MyRowKey1'
다음 예에서는 FirstName 및 LastName 속성으로 필터링합니다.
https://myaccount.table.core.windows.net/Customers()?$filter=LastName%20eq%20'Smith'%20and%20FirstName%20eq%20'John'
테이블 서비스에서는 와일드카드 쿼리가 지원되지 않습니다. 그러나 원하는 접두사에서 비교 연산자를 사용하여 접두사를 일치시킬 수 있습니다. 다음 예에서는 LastName 속성이 포함된 'A' 문자로 시작하는 엔터티를 반환합니다.
https://myaccount.table.core.windows.net/Customers()?$filter=LastName%20ge%20'A'%20and%20LastName%20lt%20'B'
숫자 속성 필터링
정수 또는 부동 소수점 숫자로 필터링하려면 따옴표 없이 URI에 상수 값을 지정합니다.
이 예에서는 해당 값이 30보다 큰 Age 속성이 포함된 모든 엔터티를 반환합니다.
https://myaccount.table.core.windows.net/Customers()?$filter=Age%20gt%2030
이 예에서는 해당 값이 100.25보다 작거나 같은 AmountDue 속성이 포함된 모든 엔터티를 반환합니다.
https://myaccount.table.core.windows.net/Customers()?$filter=AmountDue%20le%20100.25%20
부울 속성 필터링
부울 값으로 필터링하려면 따옴표 없이 true 또는 false를 지정합니다.
다음 예에서는 IsActive 속성이 true로 설정된 모든 엔터티를 반환합니다.
https://myaccount.table.core.windows.net/Customers()?$filter=IsActive%20eq%20true
DateTime 속성 필터링
DateTime 값으로 필터링하려면 URI에 datetime 키워드를 지정하고 작은 따옴표에 날짜/시간 상수를 표시합니다.
DateTime 값 서식 지정에 설명된 대로 날짜/시간 상수는 결합된 UTC 형식이어야 합니다.
다음 예에서는 CustomerSince 속성이 2008년 7월 10일과 동일한 엔터티를 반환합니다.
https://myaccount.table.core.windows.net/Customers()?$filter=CustomerSince%20eq%20datetime'2008-07-10T00:00:00Z'
GUID 속성으로 필터링
GUID 값으로 필터링하려면 URI에 guid 키워드를 지정하고 GUID 상수를 작은 따옴표로 표시합니다.
다음 예에서는 GuidValue 속성이 다음과 동일한 엔터티를 반환합니다.
https://myaccount.table.core.windows.net/Customers()?$filter=GuidValue%20eq%20guid'a455c695-df98-5678-aaaa-81d3367e5a34'
참고 항목
테이블 서비스 개념
Table Service 데이터 모델 이해
Table Service 리소스 주소 지정
쿼리 시간 제한 및 페이지 매김
테이블 서비스에 대한 LINQ 쿼리 작성