Model 클래스

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

Model 클래스는 데이터 모델 정의의 슈퍼클래스입니다.

Model은 모듈 google.appengine.ext.db에 정의됩니다.

소개

애플리케이션은 Model을 서브클래스로 포함하고 있는 클래스를 정의함으로써 데이터 모델을 정의합니다. 모델의 속성은 클래스 속성 및 Property 클래스 인스턴스를 사용하여 정의됩니다. 예를 들면 다음과 같습니다.

class Story(db.Model):
  title = db.StringProperty()
  body = db.TextProperty()
  created = db.DateTimeProperty(auto_now_add=True)

애플리케이션은 Model 클래스의 서브클래스를 인스턴스화하여 새로운 데이터 항목을 만듭니다. 항목의 속성은 인스턴스의 속성을 사용하여 할당되거나, 생성자에 대한 키워드 인수로 할당될 수 있습니다.

s = Story()
s.title = "The Three Little Pigs"

s = Story(title="The Three Little Pigs")

모델 서브클래스의 이름이 Datastore 항목 종류의 이름으로 사용됩니다. Datastore가 두 개의 밑줄(__)로 시작되는 모든 종류 이름을 예약하므로, 모델 서브클래스에 이러한 이름을 사용해서는 안 됩니다.

속성의 이름은 항목에서 상응하는 속성의 이름으로 사용됩니다. 이름이 밑줄(_)로 시작되는 모델 인스턴스 속성은 무시되므로, 애플리케이션은 이러한 속성을 사용하여 Datastore에 저장되지 않는 모델 인스턴스에 데이터를 저장할 수 있습니다.

Datastore 및 모델 클래스 API는 속성 이름 및 모델 인스턴스 속성에 여러 가지 제한을 둡니다. 전체 설명은 허용되지 않는 속성 이름을 참조하세요.

모든 항목에는 항목을 나타내는 고유 식별자인 키가 있습니다. 키는 지정된 종류의 항목 중에서 고유한 문자열인 키 이름(선택사항)을 포함할 수 있습니다. 항목의 종류와 키 이름을 Key.from_path() 및 Model.get_by_key_name() 메서드와 함께 사용하여 항목을 검색할 수 있습니다.

항목에는 선택사항인 상위 항목도 있을 수 있습니다. 상위-하위 관계는 Datastore에서 트랜잭션 및 데이터 지역을 제어하는 데 사용되는 항목 그룹을 형성합니다. 애플리케이션은 상위 항목을 하위 항목의 생성자에 parent 인수로 전달함으로써 두 항목 간에 상위-하위 관계를 만듭니다.

Model.get_or_insert() 메서드를 사용하면 존재하지 않을 수도 있는 항목을 검색하고, 필요한 경우 Datastore에 해당 항목을 만들 수 있습니다.

keyname = "some_key"
s = Story.get_or_insert(keyname, title="The Three Little Pigs")

참고: 모델 인스턴스의 항목은 명시적으로 또는 Model.get_or_insert()를 통해 처음 기록(put)되기 전까지는 Datastore에 없습니다.

모델 인스턴스 데이터의 복사본인 dict를 만들려면 db.to_dict 함수를 사용하세요.

생성자

Model 클래스의 생성자는 다음과 같이 정의됩니다.

class Model (parent=None, key_name=None, **kwds)

데이터 모델 정의의 슈퍼클래스입니다.

생성 중에 각 속성의 validate() 메서드가 호출됩니다. 해당 호출의 예외는 이 생성자의 호출자에게 전파됩니다.

인수

parent

새 항목의 상위 요소인 항목의 모델 인스턴스 또는 키 인스턴스입니다.

key_name

항목의 키 이름입니다. 이름은 기본 키에 포함됩니다. None인 경우 시스템에서 생성된 ID가 키에 사용됩니다.

key_name 값은 __*__ 형식이 아니어야 합니다.

키 이름은 str 값이 ASCII 텍스트로 변환된 유니코드 문자열로 저장됩니다.

이 객체에서 put()을 호출하면 기존의 모든 Datastore 항목을 같은 키로 덮어씁니다.

kwds

인스턴스 속성의 초기 값이며 키워드 인수로 사용됩니다. 각 이름은 Model 클래스에 정의된 속성에 해당합니다.

추가 키워드 인수

키

항목의 명시적 Key 인스턴스입니다. key_name 또는 parent와 함께 사용할 수 없습니다. None인 경우 key_name 및 parent의 동작으로 대체됩니다. allocate_ids()를 사용하여 새 항목의 숫자 ID를 예약할 때 유용합니다.

key의 값은 유효한 Key 인스턴스여야 합니다.

이 객체에서 put()을 호출하면 기존의 모든 Datastore 항목을 같은 키로 덮어씁니다.

클래스 메서드

Model 클래스의 클래스 메서드는 다음과 같습니다.

Model.get (keys)

지정된 키의 모델 인스턴스를 검색합니다. 키는 모델 종류의 항목을 나타내야 합니다. 제공된 키가 올바른 종류가 아니면 KindError 예외가 발생합니다.

이 메서드는 추가적인 유형 확인이 수반되는 db.get() 함수와 유사합니다.

인수

keys

검색할 항목의 키, 키의 문자열 표현, 키 또는 해당 문자열 표현의 목록입니다.

read_policy

원하는 수준의 데이터 일관성을 지정하는 읽기 정책입니다.

STRONG_CONSISTENCY

최신 결과를 보장하지만 단일 항목 그룹으로 제한됩니다.

EVENTUAL_CONSISTENCY

여러 항목 그룹을 포괄할 수 있지만 경우에 따라 오래된 결과를 반환하는 경우가 있습니다. 일반적으로 최종 일관성을 지닌 쿼리는 강력한 일관성을 지닌 쿼리보다 더 빨리 실행되지만 아무것도 보장되지 않습니다.

참고: 상위가 아닌 전역 쿼리는 이 인수를 무시합니다.

deadline

오류가 발생하여 중단되기 전 Datastore에서 결과를 반환하기까지 기다리는 최대 시간(초)입니다. 정수 또는 부동 소수점 값을 허용합니다. 기본값(60초)보다 높게 설정할 수는 없지만 특정 작업의 실패가 바로 도출될 수 있도록 낮게 조정할 수는 있습니다(예: 사용자에게 응답을 더 빨리 반환, 작업 재시도, 다른 작업 시도, 태스크 큐에 작업 추가).

keys가 단일 키(또는 키의 문자열 표현)로 구성되어 있는 경우 이 메서드는 키가 Datastore에 있으면 해당 키와 관련된 모델 인스턴스를 반환합니다. 그렇지 않으면 None을 반환합니다. keys가 목록인 경우 반환값은 모델 인스턴스의 해당 목록이고, 지정된 키의 항목이 없는 경우 None입니다.

db.get() 함수도 참조하세요.

Model.get_by_id (ids, parent=None)

지정된 숫자 ID의 모델 인스턴스를 검색합니다.

인수

ids

숫자 항목 ID 또는 숫자 ID 목록입니다.

parent

요청된 항목의 상위 항목(모델 또는 키) 또는 요청된 항목에 상위 항목이 없을 경우 None(기본값)입니다. 한 호출에 의해 요청된 여러 항목은 모두 상위 항목이 같아야 합니다.

read_policy

원하는 수준의 데이터 일관성을 지정하는 읽기 정책입니다.

STRONG_CONSISTENCY

최신 결과를 보장하지만 단일 항목 그룹으로 제한됩니다.

EVENTUAL_CONSISTENCY

여러 항목 그룹을 포괄할 수 있지만 경우에 따라 오래된 결과를 반환하는 경우가 있습니다. 일반적으로 최종 일관성을 지닌 쿼리는 강력한 일관성을 지닌 쿼리보다 더 빨리 실행되지만 아무것도 보장되지 않습니다.

참고: 상위가 아닌 전역 쿼리는 이 인수를 무시합니다.

deadline

오류가 발생하여 중단되기 전 Datastore에서 결과를 반환하기까지 기다리는 최대 시간(초)입니다. 정수 또는 부동 소수점 값을 허용합니다. 기본값(60초)보다 높게 설정할 수는 없지만 특정 작업의 실패가 바로 도출될 수 있도록 낮게 조정할 수는 있습니다(예: 사용자에게 응답을 더 빨리 반환, 작업 재시도, 다른 작업 시도, 태스크 큐에 작업 추가).

ids가 단일 숫자 ID로 구성되어 있는 경우 이 메서드는 ID가 Datastore에 있으면 해당 ID와 관련된 모델 인스턴스를 반환합니다. 그렇지 않으면 None을 반환합니다. ids가 목록인 경우 반환값은 모델 인스턴스의 해당 목록이고, 지정된 숫자 ID의 항목이 없는 경우 None입니다.

Model.get_by_key_name (key_names, parent=None)

지정된 키 이름의 모델 인스턴스를 검색합니다.

인수

key_names

키 이름 또는 키 이름 목록입니다.

parent

요청된 항목의 상위 항목(모델 인스턴스 또는 키) 또는 요청된 항목에 상위 항목이 없을 경우 None(기본값)입니다. 한 호출에 의해 요청된 여러 항목은 모두 상위 항목이 같아야 합니다.

read_policy

원하는 수준의 데이터 일관성을 지정하는 읽기 정책입니다.

STRONG_CONSISTENCY

최신 결과를 보장하지만 단일 항목 그룹으로 제한됩니다.

EVENTUAL_CONSISTENCY

여러 항목 그룹을 포괄할 수 있지만 경우에 따라 오래된 결과를 반환하는 경우가 있습니다. 일반적으로 최종 일관성을 지닌 쿼리는 강력한 일관성을 지닌 쿼리보다 더 빨리 실행되지만 아무것도 보장되지 않습니다.

참고: 상위가 아닌 전역 쿼리는 이 인수를 무시합니다.

deadline

오류가 발생하여 중단되기 전 Datastore에서 결과를 반환하기까지 기다리는 최대 시간(초)입니다. 정수 또는 부동 소수점 값을 허용합니다. 기본값(60초)보다 높게 설정할 수는 없지만 특정 작업의 실패가 바로 도출될 수 있도록 낮게 조정할 수는 있습니다(예: 사용자에게 응답을 더 빨리 반환, 작업 재시도, 다른 작업 시도, 태스크 큐에 작업 추가).

key_names가 단일 키 이름으로 구성되어 있는 경우 이 메서드는 이름이 Datastore에 있으면 해당 이름과 관련된 모델 인스턴스를 반환합니다. 그렇지 않으면 None을 반환합니다. key_names가 목록인 경우 반환값은 모델 인스턴스의 해당 목록이고, 지정된 키 이름의 항목이 없는 경우 None입니다.

Model.get_or_insert (key_name, **kwds)

지정된 키 이름을 사용하여 모델 종류의 항목을 가져오려고 시도합니다. 존재하면 get_or_insert()가 해당 항목을 반환합니다. 존재하지 않으면 kwds에서 지정된 종류, 이름, 매개변수를 가진 새 항목이 생성, 저장, 반환됩니다.

get과 가능한 후속 put 작업은 원자성을 보장하기 위해 트랜잭션에 래핑됩니다. 즉, get_or_insert()는 절대로 기존 항목을 덮어쓰지 않으며 지정된 종류 및 이름의 항목이 없는 경우에만 새 항목을 삽입한다는 의미입니다. 다시 말해 get_or_insert()는 다음 Python 코드와 동일합니다.

def txn(key_name, **kwds):
  entity = Story.get_by_key_name(key_name, parent=kwds.get('parent'))
  if entity is None:
    entity = Story(key_name=key_name, **kwds)
    entity.put()
  return entity

def get_or_insert(key_name, **kwargs):
  return db.run_in_transaction(txn, key_name, **kwargs)

get_or_insert('some key', title="The Three Little Pigs")

인수

key_name

항목 키의 이름입니다.

kwds

지정된 키 이름의 인스턴스가 존재하지 않는 경우 모델 클래스의 생성자에게 전달할 키워드 인수입니다. 원하는 항목에 상위 항목이 있는 경우에는 parent 인수가 필요합니다.

참고: get_or_insert()는 read_policy 또는 deadline 인수를 허용하지 않습니다.

이 메서드는 원래부터 존재했건 아니면 메서드에 의해 만들어졌건 요청된 항목을 나타내는 모델 클래스의 인스턴스를 반환합니다. 모든 Datastore 작업과 마찬가지로 이 메서드는 트랜잭션을 완료할 수 없는 경우 TransactionFailedError를 발생시킬 수 있습니다.

Model.all (keys_only=False)

이 모델에 해당하는 종류의 모든 항목을 나타내는 Query 객체를 반환합니다. 쿼리 객체의 메서드는 실행되기 전에 쿼리에 필터 및 정렬 순서를 적용할 수 있습니다. 자세한 내용은 Query 클래스 페이지를 참조하세요.

인수

keys_only

쿼리가 전체 항목을 반환해야 하는지 아니면 키만 반환해야 하는지의 여부입니다. 키를 반환하는 쿼리는 전체 항목을 반환하는 쿼리보다 빠르고 CPU 시간을 덜 소비합니다.

Model.gql (query_string, *args, **kwds)

이 모델의 인스턴스에 GQL 쿼리를 수행합니다.

인수

query_string

SELECT * FROM model 이후의 GQL 쿼리 부분입니다(이 클래스의 메서드 사용에 포함되어 있음).

args

GqlQuery() 생성자와 비슷한 위치 매개변수 바인딩입니다.

kwds

GqlQuery() 생성자와 비슷한 키워드 매개변수 바인딩입니다.

s = Story.gql("WHERE title = :1", "Little Red Riding Hood")

s = Story.gql("WHERE title = :title", title="Little Red Riding Hood")

반환 값은 결과에 액세스하는 데 사용할 수 있는 GqlQuery 객체입니다.

Model.kind()

모델의 종류를 반환합니다. 주로 Model 서브클래스의 이름입니다.

Model.properties ()

이 모델 클래스에 정의된 모든 속성의 사전을 반환합니다.

인스턴스 메소드

Model 인스턴스에는 다음과 같은 메소드가 있습니다.

key ()

이 모델 인스턴스의 Datastore Key를 반환합니다.

모델 인스턴스의 키에는 인스턴스의 항목 종류와 고유 식별자가 포함됩니다. 식별자는 인스턴스가 만들어질 때 애플리케이션에서 명시적으로 할당하는 키 이름 문자열일 수도 있고, 인스턴스가 Datastore에 기록(put)될 때 App Engine에서 자동으로 할당하는 정수 숫자 ID일 수도 있습니다. 인스턴스에 식별자가 할당되기 전에 key()를 호출하면 NotSavedError 예외가 발생합니다.

put ()

모델 인스턴스를 Datastore에 저장합니다. 모델 인스턴스가 새로 만들어졌으며 이전에 저장된 적이 없는 경우, 이 메소드는 Datastore에서 새 데이터 항목을 만듭니다. 그렇지 않은 경우에는 데이터 항목을 현재 속성 값으로 업데이트합니다.

이 메서드는 저장된 항목의 키를 반환합니다.

데이터를 커밋할 수 없으면 TransactionFailedError 예외가 발생합니다.

인수

deadline

오류가 발생하여 중단되기 전 Datastore에서 결과를 반환하기까지 기다리는 최대 시간(초)입니다. 정수 또는 부동 소수점 값을 허용합니다. 기본값(60초)보다 높게 설정할 수는 없지만 특정 작업의 실패가 바로 도출될 수 있도록 낮게 조정할 수는 있습니다(예: 사용자에게 응답을 더 빨리 반환, 작업 재시도, 다른 작업 시도, 작업 대기열에 작업 추가).

delete ()

Datastore에서 모델 인스턴스를 삭제합니다. 인스턴스가 Datastore에 기록(put)된 적이 없으면 delete가 NotSavedError 예외를 발생시킵니다.

인수

deadline

오류가 발생하여 중단되기 전 Datastore에서 결과를 반환하기까지 기다리는 최대 시간(초)입니다. 정수 또는 부동 소수점 값을 허용합니다. 기본값(60초)보다 높게 설정할 수는 없지만 특정 작업의 실패가 바로 도출될 수 있도록 낮게 조정할 수는 있습니다(예: 사용자에게 응답을 더 빨리 반환, 작업 재시도, 다른 작업 시도, 작업 대기열에 작업 추가).

is_saved ()

모델 인스턴스가 한 번이라도 Datastore에 기록(put)되었으면 True를 반환합니다.

이 메서드는 인스턴스가 생성된 이후에 한 번이라도 Datastore에 기록되었는지 여부만 확인합니다. 마지막으로 기록된 이후에 인스턴스의 속성이 업데이트되었는지 여부는 확인하지 않습니다.

dynamic_properties ()

이 모델 인스턴스에 정의된 모든 동적 속성의 이름이 포함된 목록을 반환합니다. Expando 클래스의 인스턴스에만 적용됩니다. Expando 모델이 아닌 인스턴스의 경우에는 빈 목록을 반환합니다.

parent ()

이 인스턴스의 상위 항목에 대한 모델 인스턴스를 반환하거나, 인스턴스에 상위 항목이 없는 경우 None을 반환합니다.

parent_key ()

이 인스턴스의 상위 항목에 대한 Key를 반환하거나, 인스턴스에 상위 항목이 없는 경우 None을 반환합니다.

to_xml ()

모델 인스턴스의 XML 표현을 반환합니다.

속성 값은 Atom 및 데이터 사양을 준수합니다.

허용되지 않는 속성 이름

Datastore 및 해당 API는 항목 속성 및 모델 인스턴스 속성의 이름에 여러 가지 제한을 둡니다.

Datastore가 두 개의 밑줄(__*__)로 시작되고 끝나는 모든 속성 이름을 예약하므로, Datastore 항목에는 이러한 이름이 사용된 속성을 포함할 수 없습니다.

Python 모델 API는 밑줄(_)로 시작되는 Model 또는 Expando 클래스의 모든 속성을 무시합니다. 애플리케이션은 이러한 속성을 사용하여 Datastore에 저장되지 않는 모델 객체에 데이터를 연결할 수 있습니다.

마지막으로 Python 모델 API는 객체 속성을 사용하여 모델의 속성을 정의하며, 기본적으로 Datastore 항목 속성의 이름은 이 속성을 따라 지정됩니다. Model 클래스에는 다른 용도의 속성과 인스턴스가 여러 개 있기 때문에 이러한 속성을 Python API의 속성에 사용하면 안 됩니다. 예를 들어 Model에는 key 속성을 사용하여 액세스하는 속성이 있을 수 없습니다.

하지만 속성은 속성 생성자에 name 인수를 지정함으로써 속성 이름과 다른 이름을 Datastore에 지정할 수 있습니다. 따라서 Datastore 항목은 Model 클래스에 예약된 속성과 비슷한 속성 이름을 가질 수 있으며, 클래스에서 다른 속성 이름을 사용할 수 있습니다.

class MyModel(db.Model):
  obj_key = db.StringProperty(name="key")

다음 속성 이름은 Python API에서 Model 클래스에 의해 예약됩니다.

all app copy delete entity entity_type fields from_entity get gql instance_properties

is_saved key key_name kind parent parent_key properties put setdefault to_xml update