항목, 속성, 키

참고: 새로운 애플리케이션을 빌드하는 개발자는 NDB 클라이언트 라이브러리를 사용하는 것이 좋습니다. NDB 클라이언트 라이브러리는 이 클라이언트 라이브러리와 비교 시 Memcache API를 통한 자동 항목 캐싱과 같은 여러 가지 이점을 제공합니다. 현재 기존 DB 클라이언트 라이브러리를 사용하는 중이라면 DB에서 NDB로의 마이그레이션 가이드를 참조하세요.

Cloud Datastore의 데이터 객체를 항목이라고 부릅니다. 항목에는 하나 이상의 명명된 속성이 있으며 각 속성에는 하나 이상의 값이 있을 수 있습니다. 같은 종류의 항목이라도 속성이 동일할 필요는 없으며, 항목의 특정 속성 값이 모두 동일한 데이터 유형이 아니어도 됩니다. 필요한 경우 애플리케이션이 자체 데이터 모델에 이러한 제한을 설정하고 시행할 수 있습니다.

Cloud Datastore에서 지원되는 속성 값의 데이터 유형은 다양하며, 여기에는 다음 사항이 포함됩니다.

  • 정수
  • 부동 소수점 수
  • 문자열
  • 날짜
  • 바이너리 데이터

전체 유형 목록은 속성 및 값 유형을 참조하세요.

Cloud Datastore의 각 항목에는 항목을 고유하게 식별하는 가 있습니다. 키는 다음 구성요소로 구성됩니다.

  • 멀티테넌시를 허용하는 항목의 네임스페이스
  • Cloud Datastore 쿼리 목적으로 분류되는 항목 종류
  • 다음 중 하나에 해당하는 개별 항목의 식별자
    • 키 이름 문자열
    • 정수 숫자 ID
  • Cloud Datastore 계층 구조에서 항목으로 연결되는 선택적 상위 경로

애플리케이션은 항목의 키를 사용하여 Cloud Datastore에서·개별 항목을 가져오거나 항목 키 또는 속성 값에 따라 쿼리를 실행하여 항목을 한 개 이상 검색할 수 있습니다.

Python App Engine SDK에는 Cloud Datastore 항목을 Python 클래스의 인스턴스로 나타내고, 이러한 인스턴스를 Datastore에 저장하고 검색하기 위한 데이터 모델링 라이브러리가 포함되어 있습니다.

Cloud Datastore 자체는 지정된 속성에 특정 유형의 값이 포함되는지 여부와 같은 항목 구조에 대한 어떠한 제한도 적용하지 않습니다. 이러한 작업은 애플리케이션 및 데이터 모델링 라이브러리에서 수행됩니다.

종류 및 식별자

각 Cloud Datastore 항목은 쿼리 목적으로 항목을 분류하는 특정 종류에 속합니다. 예를 들어 인사 관리 애플리케이션은 회사의 각 직원을 종류가 Employee인 항목으로 나타낼 수 있습니다. Python Datastore API에서 항목 종류는 해당 모델 클래스에 따라 결정되며, 이러한 클래스는 애플리케이션에서 데이터 모델링 라이브러리 클래스인 db.Model의 서브클래스로 정의됩니다. 모델 클래스 이름은 여기에 속하는 항목의 종류가 됩니다. 두 개의 밑줄(__)로 시작하는 종류 이름은 모두 예약되어 있으며 사용할 수 없습니다.

다음 예시에서는 Employee 종류의 항목을 만들고, 해당 속성 값을 채우고, 이를 Datastore에 저장합니다.

import datetime
from google.appengine.ext import db

class Employee(db.Model):
  first_name = db.StringProperty()
  last_name = db.StringProperty()
  hire_date = db.DateProperty()
  attended_hr_training = db.BooleanProperty()

employee = Employee(first_name='Antonio',
                    last_name='Salieri')

employee.hire_date = datetime.datetime.now().date()
employee.attended_hr_training = True

employee.put()

Employee 클래스는 데이터 모델의 4가지 속성 first_name, last_name, hire_date, attended_hr_training을 선언합니다. Model 슈퍼클래스는 Employee 객체 속성이 이 모델을 준수하도록 보장합니다. 예를 들어 hire_date 속성에 문자열 값을 할당하려 하면 런타임 오류가 발생합니다. 이는 hire_date의 데이터 모델이 db.DateProperty로 선언되었기 때문입니다.

종류 외에도 각 항목에는 항목이 생성될 때 할당된 식별자가 있습니다. 식별자는 항목 키의 일부이므로 항목과 영구적으로 연관되며 변경할 수 없습니다. 식별자를 할당할 수 있는 두 가지 방법은 다음과 같습니다.

  • 애플리케이션에서 항목에 대한 고유한 키 이름 문자열을 지정할 수 있습니다.
  • Cloud Datastore에서 항목에 정수 숫자 ID를 자동으로 할당하도록 할 수 있습니다.

항목에 키 이름을 할당하려면 항목을 만들 때 이름이 지정된 인수 key_name을 모델 클래스 생성자에 제공합니다.

# Create an entity with the key Employee:'asalieri'.
employee = Employee(key_name='asalieri')

Cloud Datastore가 숫자 ID를 자동으로 할당하도록 하려면 key_name 인수를 생략합니다.

# Create an entity with a key such as Employee:8261.
employee = Employee()

식별자 할당

두 가지 자동 ID 정책을 사용하여 자동으로 ID를 생성하도록 Cloud Datastore를 구성할 수 있습니다.

  • default 정책은 거의 균일하게 배포되는 미사용 ID의 임의 시퀀스를 생성합니다. 각 ID는 최대 16자리 숫자입니다.
  • legacy 정책은 연속적이지 않은 더 작은 정수 ID 시퀀스를 만듭니다.

사용자에게 항목 ID를 표시하거나 항목 ID의 순서를 결정하려는 경우 수동으로 할당하는 것이 좋습니다.

Cloud Datastore는 거의 균일하게 배포되는 미사용 ID의 임의 시퀀스를 생성합니다. 각 ID는 최대 16자리 숫자입니다.

시스템 할당 ID 값은 항목 그룹에 고유합니다. 한 개의 항목 그룹 또는 네임스페이스에서 다른 그룹이나 네임스페이스로 항목을 복사하고 키의 ID 부분을 보존하려는 경우, ID를 먼저 할당하여 이후의 할당에서 Cloud Datastore가 해당 ID를 선택하지 못하도록 합니다.

상위 경로

Cloud Datastore의 항목은 파일 시스템의 디렉터리 구조와 유사한 계층 구조 형식의 공간을 형성합니다. 항목을 만들 때 선택적으로 다른 항목을 상위 요소로 지정할 수 있으며, 새 항목은 상위 항목의 하위 요소가 됩니다. 파일 시스템과 달리 상위 항목이 실제로 존재할 필요는 없습니다. 상위 요소가 없는 항목은 루트 항목입니다. 항목과 상위 요소 간의 연결은 영구적이며 항목이 생성되면 변경할 수 없습니다. Cloud Datastore는 상위 요소가 동일한 2개의 항목 또는 2개의 루트 항목(상위 요소가 없는 항목)에 동일한 숫자 ID를 할당하지 않습니다.

항목의 상위 요소, 상위 요소의 상위 요소 등은 재귀적으로 해당 항목의 상위가 되고, 항목의 하위 요소, 하위 요소의 하위 요소 등은 해당 항목의 하위가 됩니다. 루트 항목과 그 하위에 있는 모든 항목은 동일한 항목 그룹에 속합니다. 루트 항목에서 시작하여 상위 요소에서 하위 요소로 진행되고 지정된 항목까지 이어지는 항목의 시퀀스를 해당 항목의 상위 경로라고 합니다. 항목을 식별하는 전체 키는 상위 경로를 지정하고 항목 자체로 종료되는 종류-식별자 쌍의 시퀀스로 구성됩니다.

[Person:GreatGrandpa, Person:Grandpa, Person:Dad, Person:Me]

루트 항목의 경우 상위 경로는 비어 있으며 키는 항목의 고유한 종류 및 식별자로만 구성됩니다.

[Person:GreatGrandpa]

이 개념은 다음 다이어그램에서 설명합니다.

항목 그룹에서 루트 항목과 하위 항목의 관계 표시

항목의 상위를 지정하려면 하위 항목을 만들 때 모델 클래스 생성자에 parent 인수를 사용합니다. 이 인수 값은 상위 항목 자체이거나 키일 수 있습니다. 상위 항목의 key() 메서드를 호출하여 키를 가져올 수 있습니다. 다음 예에서는 Address 종류의 항목을 만들고 Employee 항목을 해당 상위로 지정하는 두 가지 방법을 보여줍니다.

# Create Employee entity
employee = Employee()
employee.put()

# Set Employee as Address entity's parent directly...
address = Address(parent=employee)

# ...or using its key
e_key = employee.key()
address = Address(parent=e_key)

# Save Address entity to datastore
address.put()

트랜잭션 및 항목 그룹

항목을 생성, 업데이트 또는 삭제하려는 모든 시도는 트랜잭션의 관점에서 수행됩니다. 단일 트랜잭션에 포함할 수 있는 이러한 작업의 수에는 제한이 없습니다. 데이터의 일관성을 유지하기 위해 트랜잭션은 포함된 모든 작업을 Cloud Datastore에 하나의 단위로 적용합니다. 즉, 작업이 하나라도 실패하면 어떠한 작업도 적용하지 않습니다. 또한 동일 트랜잭션 내에서 수행되는 모든 강력한 일관성의 읽기(상위 쿼리 또는 get)에서 데이터의 일관된 스냅샷이 관찰됩니다.

위에 언급한 대로 항목 그룹은 상위 항목을 통해 공통 루트 요소로 연결되는 항목 집합입니다. 데이터를 항목 그룹으로 구성하면 수행 가능한 트랜잭션을 제한할 수 있습니다.

  • 트랜잭션에서 액세스하는 모든 데이터는 최대 25개의 항목 그룹에만 포함될 수 있습니다.
  • 트랜잭션 내에서 쿼리를 사용하려면 올바른 데이터에 일치하는 상위 필터를 지정할 수 있는 방식으로 데이터가 항목 그룹으로 구성되어 있어야 합니다.
  • 단일 항목 그룹 내에서는 쓰기 처리량 한도가 초당 약 1개의 트랜잭션으로 제한되어 있습니다. 이 한도가 존재하는 이유는 Cloud Datastore가 높은 안정성과 내결함성을 제공하기 위해 광범위한 지리적 영역에 걸쳐 각 항목 그룹의 마스터 없는 동기 복제 작업을 수행하기 때문입니다.

많은 애플리케이션에서 관련성이 없는 데이터를 포괄적으로 확인할 때는 eventual consistency(예: 여러 항목 그룹에 걸친 비상위 쿼리로 약간 오래된 데이터를 반환할 수 있음)를 사용하고, 관련성이 높은 단일 데이터세트를 보거나 수정할 때는 상위 쿼리 또는 단일 항목의 get과 같은 strong consistency를 사용하는 것이 적합할 수 있습니다. 이러한 애플리케이션에서는 일반적으로 관련성이 높은 각 데이터세트마다 별도의 항목 그룹을 사용하는 방식이 바람직합니다. 자세한 내용은 Strong Consistency를 위한 구조화를 참조하세요.

속성 및 값 유형

항목과 연관된 데이터 값은 하나 이상의 속성으로 구성됩니다. 각 속성에는 이름과 하나 이상의 값이 있습니다. 속성에는 둘 이상의 유형 값이 있을 수 있으며, 두 개의 항목에 동일한 속성의 서로 다른 유형 값이 있을 수 있습니다. 속성은 색인 생성되거나 색인 생성되지 않을 수 있으며, 속성 P를 기준으로 정렬 또는 필터링하는 쿼리는 P가 색인 생성되지 않은 항목을 무시합니다. 항목 하나에 포함될 수 있는 색인 생성된 속성은 최대 20,000개입니다.

지원되는 값 유형은 다음과 같습니다.

값 유형 Python 유형 정렬 순서 참고
정수 int
long
숫자 부호 있는 64비트 정수
부동 소수점 수 float 숫자 64비트 배정밀도,
IEEE 754
부울 bool False < True
텍스트 문자열(short) str
unicode
유니코드
(str이 ASCII로 처리됨)
최대 1500바이트
텍스트 문자열(long) db.Text 없음 최대 1MB

색인이 생성되지 않음
바이트 문자열(short) db.ByteString 바이트순 최대 1500바이트
바이트 문자열(long) db.Blob 없음 최대 1MB

색인이 생성되지 않음
날짜 및 시간 datetime.date
datetime.time
datetime.datetime
시간순
지리적 지점 db.GeoPt 위도별,
이후 경도별
우편 주소 db.PostalAddress 유니코드
전화번호 db.PhoneNumber 유니코드
이메일 주소 db.Email 유니코드
Google 계정 사용자 users.User 이메일 주소
유니코드 순
채팅 메시지 핸들 db.IM 유니코드
링크 db.Link 유니코드
카테고리 db.Category 유니코드
평가 db.Rating 숫자
Cloud Datastore 키 db.Key 경로 요소별
(종류, 식별자,
종류, 식별자...)
Blobstore 키 blobstore.BlobKey 바이트순
Null NoneType 없음

중요: UserProperty에는 이메일 주소와 사용자의 고유 ID가 포함되어 있으므로 이를 저장하지 않는 것이 좋습니다. 사용자가 이메일 주소를 변경한 경우 이전에 저장된 User 값과 새로운 User 값을 비교하면 서로 일치하지 않습니다.

텍스트 문자열 및 인코딩되지 않은 바이너리 데이터(바이트 문자열)에 대해 Cloud Datastore는 두 가지 값 유형을 지원합니다.

  • short 문자열(최대 1500바이트)은 색인이 생성되고 쿼리 필터 조건 및 정렬 순서에 사용될 수 있습니다.
  • long 문자열(최대 1MB)은 색인이 생성되지 않으며 쿼리 필터 및 정렬 순서에 사용될 수 없습니다.
참고: long 바이트 문자열 유형은 Cloud Datastore API에서 Blob으로 이름이 지정되지만 Blobstore API에서 사용되는 blob과는 관련이 없습니다.

쿼리에 포함된 속성 값에 여러 유형이 혼용된 경우 Cloud Datastore는 내부 표현을 기준으로 명확한 순서를 사용합니다.

  1. Null 값
  2. 고정 소수점 수
    • 정수
    • 날짜 및 시간
    • 평가
  3. 부울 값
  4. 바이트 시퀀스
    • 바이트 문자열
    • 유니코드 문자열
    • Blobstore 키
  5. 부동 소수점 수
  6. 지리적 지점
  7. Google 계정 사용자
  8. Cloud Datastore 키

long 텍스트 문자열 및 long 바이트 문자열은 색인이 생성되지 않기 때문에 순서가 정의되지 않습니다.

항목 작업

애플리케이션에서는 Cloud Datastore API를 사용하여 항목을 생성, 검색, 업데이트, 삭제할 수 있습니다. 애플리케이션이 항목의 전체 키를 알고 있거나 상위 키, 종류, 식별자에서 파생시킬 수 있는 경우 해당 키를 사용하여 항목에서 직접 작동할 수 있습니다. 또한 애플리케이션이 Cloud Datastore 쿼리 결과로 항목 키를 가져올 수 있습니다. 자세한 내용은 Datastore 쿼리 페이지를 참조하세요.

항목 생성

Python에서는 모델 클래스의 인스턴스를 생성하고, 필요에 따라 속성을 채우고, Datastore에 저장하도록 put() 메서드를 호출하여 새 항목을 만듭니다. 항목의 키 이름을 지정하려면 생성자에 key_name 인수를 전달하면 됩니다.

employee = Employee(key_name='asalieri',
                    first_name='Antonio',
                    last_name='Salieri')

employee.hire_date = datetime.datetime.now().date()
employee.attended_hr_training = True

employee.put()

키 이름을 제공하지 않으면 Cloud Datastore가 해당 항목 키의 숫자 ID를 자동으로 생성합니다.

employee = Employee(first_name='Antonio',
                    last_name='Salieri')

employee.hire_date = datetime.datetime.now().date()
employee.attended_hr_training = True

employee.put()

항목 검색

지정된 키로 식별되는 항목을 검색하려면 Key 객체를 db.get() 함수의 인수로 전달합니다. 클래스 메서드 Key.from_path()를 사용하여 Key 객체를 생성할 수 있습니다. 전체 경로는 상위 경로에 있는 항목 시퀀스이며, 각 항목은 해당 종류(문자열)와 해당 식별자(키 이름 또는 숫자 ID)로 표시됩니다.

address_k = db.Key.from_path('Employee', 'asalieri', 'Address', 1)
address = db.get(address_k)

db.get()은 적합한 모델 클래스의 인스턴스를 반환합니다. 검색 중인 항목의 모델 클래스를 가져왔는지 확인하세요.

항목 업데이트

기존 항목을 업데이트하려면 객체 속성을 수정한 후 put() 메서드를 호출합니다. 이렇게 하면 객체 데이터가 기존 항목을 덮어씁니다. put()을 호출할 때마다 전체 객체가 Cloud Datastore로 전송됩니다.

속성을 삭제하려면 Python 객체에서 속성을 삭제합니다.

del address.postal_code

그런 다음 객체를 저장합니다.

항목 삭제

항목 키가 제공되면 db.delete() 함수를 사용하여 항목을 삭제할 수 있습니다.

address_k = db.Key.from_path('Employee', 'asalieri', 'Address', 1)
db.delete(address_k)

또는 항목의 고유 delete() 메서드를 호출하여 삭제할 수 있습니다.

employee_k = db.Key.from_path('Employee', 'asalieri')
employee = db.get(employee_k)

# ...

employee.delete()

일괄 작업

db.put(), db.get(), db.delete() 함수(및 비동기 상대 함수 db.put_async(), db.get_async(), db.delete_async())는 단일 Cloud Datastore 호출에서 목록 인수를 수락하여 여러 항목에 작업을 수행할 수 있습니다.

# A batch put.
db.put([e1, e2, e3])

# A batch get.
entities = db.get([k1, k2, k3])

# A batch delete.
db.delete([k1, k2, k3])

일괄 작업을 수행해도 비용은 변하지 않습니다. 각 키가 있는지 여부와 관계없이 일괄 처리된 작업에서 모든 키에 요금이 부과됩니다. 작업과 관련된 항목 크기는 비용에 영향을 주지 않습니다.

대량 항목 삭제

다량의 항목을 삭제해야 한다면 Cloud Dataflow를 사용하여 항목을 대량으로 삭제하는 것이 좋습니다.

빈 목록 사용

NDB 인터페이스에서 Cloud Datastore는 지금까지 정적 및 동적 속성 모두에 대해 빈 목록을 생략된 속성으로 작성했습니다. 하위 호환성 유지를 위해 이 동작은 계속 기본적으로 적용됩니다. 이를 전역으로 또는 ListProperty별 기준에 따라 재정의하려면 속성 클래스에서 write_empty_list 인수를 true로 설정합니다. 그러면 빈 목록이 Cloud Datastore에 작성되고 빈 목록으로 읽힐 수 있습니다.

DB 인터페이스의 경우 빈 목록 쓰기는 속성이 동적인 경우 지금까지 전혀 허용되지 않았으며, 이를 시도하면 오류가 발생했습니다. 즉, DB 동적 속성의 경우 하위 호환성을 위해 보존해야 할 기본 동작이 없습니다. 따라서 동적 모델에서는 특별한 변경사항 없이도 단순히 빈 목록을 쓰고 읽을 수 있습니다.

하지만 DB 정적 속성의 경우에는 빈 목록이 생략된 속성으로 작성되었습니다. 이 동작은 하위 호환성을 위해 계속 유지됩니다. DB 정적 속성에 빈 목록을 설정하려면 속성 클래스에서 write_empty_list 인수를 true로 사용합니다. 그러면 빈 목록이 Cloud Datastore에 작성됩니다.

이 페이지가 도움이 되었나요? 평가를 부탁드립니다.

다음에 대한 의견 보내기...

Python 2용 App Engine 표준 환경