참고: Go 1.11은 2024년 1월 30일 지원 종료되었습니다. 기존 Go 1.11 애플리케이션을 계속 실행하고 트래픽을 수신합니다. 그러나 지원 종료 날짜 이후에는 해당 런타임을 사용하는 애플리케이션의 재배포를 App Engine에서 차단할 수 있습니다. 지원되는 최신 Go 버전으로 마이그레이션하는 것이 좋습니다.

google.golang.org/appengine/datastore 패키지(v1.6.8)

datastore 패키지는 App Engine의 Datastore 서비스를 위한 클라이언트를 제공합니다.

기본 작업

항목은 스토리지 단위이며 키와 연결됩니다. 키는 선택적 상위 키, 문자열 애플리케이션 ID, 문자열 종류(항목 유형이라고도 함), StringID/IntID로 구성됩니다. StringID는 항목 이름 또는 키 이름이라고도 합니다.

StringID 0과 IntID 0을 사용하여 불완전 키라고 하는 키를 만들 수 있으며, 이러한 키는 저장된 항목을 나타내지 않습니다. 불완전 키를 사용하여 항목을 Datastore에 저장하면 해당 항목에 대해 0이 아닌 IntID를 사용하는 고유 키가 생성됩니다.

항목 내용은 대/소문자를 구분하는 필드 이름과 값의 매핑입니다. 유효한 값 유형은 다음과 같습니다.

부호 있는 정수(int, int8, int16, int32, int64),
bool,
string,
float32 and float64,
[]byte(최대 길이 1MB)
기본 유형이 위에 사전 선언된 유형 중 하나인 모든 유형
ByteString
*Key
time.Time(마이크로초 정밀도로 저장됨)
appengine.BlobKey
appengine.GeoPoint
필드가 모두 유효한 값 유형인 구조체
위 항목의 모든 슬라이스

구조체 슬라이스와 슬라이스가 포함된 구조체도 유효합니다. 그러나 하나의 구조체에 다른 구조체가 포함된 경우에는 그 중 하나만 반복될 수 있습니다. 따라서 재귀적으로 정의된 구조체 유형, 즉 직접 또는 간접적으로 []T를 포함하는 구조체 T는 유효하지 않습니다.

Get 함수와 Put 함수는 각각 항목의 내용을 로드하고 저장합니다. 항목 내용은 일반적으로 구조체 포인터로 표현됩니다.

예시 코드:

type Entity struct {
    Value string
}

func handle(w http.ResponseWriter, r *http.Request) {
    ctx := appengine.NewContext(r)

    k := datastore.NewKey(ctx, "Entity", "stringID", 0, nil)
    e := new(Entity)
    if err := datastore.Get(ctx, k, e); err != nil {
        http.Error(w, err.Error(), 500)
        return
    }

    old := e.Value
    e.Value = r.URL.Path

    if _, err := datastore.Put(ctx, k, e); err != nil {
        http.Error(w, err.Error(), 500)
        return
    }

    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    fmt.Fprintf(w, "old=%q\nnew=%q\n", old, e.Value)
}

GetMulti, PutMulti, DeleteMulti는 Get, Put, Delete 함수의 일괄 처리 버전입니다. 이러한 함수는 인수로 *Key 대신 []*Key를 사용하며, 부분적인 오류가 발생할 경우 appengine.MultiError를 반환할 수 있습니다.

속성

항목 내용은 다양한 유형으로 표현될 수 있습니다. 일반적으로 구조체 포인터가 사용되지만 PropertyLoadSaver 인터페이스를 구현하는 유형도 사용될 수 있습니다. 구조체 포인터를 사용하는 경우에는 Datastore가 리플렉션을 통해 자동으로 변환되므로 PropertyLoadSaver 인터페이스를 명시적으로 구현할 필요가 없습니다. 구조체 포인터가 이 인터페이스를 구현한다면 해당 메소드는 구조체 포인터의 기본 동작보다 우선적으로 사용됩니다. 구조체 포인터는 보다 강력한 유형으로서 사용하기 쉬우며, PropertyLoadSaver는 보다 유연합니다.

Get 호출과 Put 호출 간에, 또는 여러 Datastore 호출 간에 전달되는 실제 유형이 일치하지 않아도 됩니다. 예를 들어 *PropertyList를 저장한 후 동일한 항목을 *myStruct로 가져오거나, *myStruct0를 저장한 후 *myStruct1을 가져올 수 있습니다. 개념적으로 모든 항목은 일련의 속성으로 저장되고, 속성별로 대상 값에 로드됩니다. 구조체 포인터로 로드 시 항목을 완전하게 표현할 수 없으면(누락된 필드 등) ErrFieldMismatch 오류가 발생하지만 이 오류를 심각한 오류, 복구 가능한 오류, 무시 가능한 오류 중 무엇으로 처리할지는 호출자가 결정합니다.

기본적으로 구조체 포인터의 경우 모든 속성의 색인이 생성될 수 있으며, 속성 이름은 필드 이름과 동일합니다(따라서 대문자로 시작해야 합니다).

필드에는 datastore:"name,options" 태그가 있을 수 있습니다. 이 태그 이름은 속성 이름으로서, 하나 이상의 유효한 Go 식별자가 '.'로 결합되어야 하지만 소문자로 시작할 수 있습니다. 태그 이름이 비어 있으면 필드 이름만 사용함을 의미합니다. '-' 태그 이름은 Datastore에서 해당 필드가 무시됨을 의미합니다.

유일하게 'omitempty' 및 'noindex' 옵션만 사용할 수 있습니다.

옵션이 'omitempty'를 포함하고 필드 값이 비어 있는 경우 저장 시 필드가 생략됩니다. 빈 값은 false, 0, 모든 nil 인터페이스 값, 길이가 0인 배열, 슬라이스, 맵, 문자열입니다. 구조체 필드 값은 빈 상태일 수 없습니다.

'noindex' 옵션이 지정되면 필드 색인이 생성되지 않습니다. 모든 필드의 색인은 기본적으로 생성됩니다. 1500바이트를 초과하는 문자열 또는 바이트 슬라이스의 경우 색인을 생성할 수 없습니다. 긴 문자열 및 바이트 슬라이스를 저장하는 데 사용되는 필드는 "noindex" 태그가 지정되어야 하며, 그렇지 않은 경우 Put 작업이 실패합니다.

여러 옵션을 함께 사용하려면 쉼표로 구분하세요. 순서는 중요하지 않습니다.

"" 옵션의 경우에는 쉼표를 생략할 수 있습니다.

예시 코드:

// A and B are renamed to a and b.
// A, C and J are not indexed.
// D's tag is equivalent to having no tag at all (E).
// I is ignored entirely by the datastore.
// J has tag information for both the datastore and json packages.
type TaggedStruct struct {
    A int `datastore:"a,noindex"`
    B int `datastore:"b"`
    C int `datastore:",noindex"`
    D int `datastore:""`
    E int
    I int `datastore:"-"`
    J int `datastore:",noindex" json:"j"`
}

구조화된 속성

포인터가 가리키는 구조체에 다른 구조체가 포함된 경우, 중첩 또는 포함된 구조체가 평면화됩니다. 예를 들어 구조체 정의가 다음과 같다고 가정합니다.

type Inner1 struct {
    W int32
    X string
}

type Inner2 struct {
    Y float64
}

type Inner3 struct {
    Z bool
}

type Outer struct {
    A int16
    I []Inner1
    J Inner2
    Inner3
}

이 경우 Outer의 속성은 다음과 같게 됩니다.

type OuterEquivalent struct {
    A     int16
    IDotW []int32  `datastore:"I.W"`
    IDotX []string `datastore:"I.X"`
    JDotY float64  `datastore:"J.Y"`
    Z     bool
}

Outer에 포함된 Inner3 필드에 datastore:"Foo" 태그가 지정된 경우 해당 필드는 FooDotZ bool datastore:"Foo.Z"입니다.

외부 구조체에 "noindex" 태그가 지정되었다면, 모든 암시적 평면화 필드는 사실상 "noindex"입니다.

PropertyLoadSaver 인터페이스

PropertyLoadSaver 인터페이스를 구현하는 유형으로 항목 내용을 표현할 수도 있습니다. 이 유형은 구조체 포인터일 수도 있고 그렇지 않을 수도 있습니다. datastore 패키지는 항목 내용을 가져올 때 Load를 호출하고, 항목 내용을 저장할 때 Save를 호출합니다. 가능한 용도로는 저장되지 않는 필드 파생, 필드 확인, 필드 색인 생성(값이 양수인 경우에만) 등이 있습니다.

예시 코드:

type CustomPropsExample struct {
    I, J int
    // Sum is not stored, but should always be equal to I + J.
    Sum int `datastore:"-"`
}

func (x *CustomPropsExample) Load(ps []datastore.Property) error {
    // Load I and J as usual.
    if err := datastore.LoadStruct(x, ps); err != nil {
        return err
    }
    // Derive the Sum field.
    x.Sum = x.I + x.J
    return nil
}

func (x *CustomPropsExample) Save() ([]datastore.Property, error) {
    // Validate the Sum field.
    if x.Sum != x.I + x.J {
        return nil, errors.New("CustomPropsExample has inconsistent sum")
    }
    // Save I and J as usual. The code below is equivalent to calling
    // "return datastore.SaveStruct(x)", but is done manually for
    // demonstration purposes.
    return []datastore.Property{
        {
            Name:  "I",
            Value: int64(x.I),
        },
        {
            Name:  "J",
            Value: int64(x.J),
        },
    }, nil
}

*PropertyList 유형은 PropertyLoadSaver를 구현하며, 따라서 임의의 항목 내용을 보존할 수 있습니다.

쿼리

쿼리는 항목 속성 또는 키 상위 항목을 기준으로 항목을 검색합니다. 쿼리를 실행하면 키나 (키, 항목) 쌍으로 구성된 결과 반복기가 생성됩니다. 쿼리는 재사용 가능하며, 동시 goroutine에서 Query.Run을 호출하는 것이 안전합니다. 반복기는 동시 사용 용도로는 안전하지 않습니다.

쿼리는 변경할 수 없으며, NewQuery를 호출하여 생성하거나 새 쿼리 값을 반환하는 Filter 또는 Order 같은 메소드를 호출하여 기존 쿼리에서 파생시킬 수 있습니다. 쿼리는 일반적으로 NewQuery를 호출한 다음 이러한 메소드를 0개 이상 연속해서 호출하는 방법으로 구성됩니다. 이러한 메소드에는 다음이 포함됩니다.

Ancestor(상위) 및 Filter(필터)는 쿼리를 실행하여 반환되는 항목을 제한합니다.
Order(순서)는 반환되는 순서에 영향을 줍니다.
Project(프로젝트)는 반환되는 필드를 제한합니다.
Distinct(고유)는 프로젝션된 항목의 중복을 삭제합니다.
KeysOnly는 반복자가 (키, 항목) 쌍이 아닌 키만 반환하도록 합니다.
Start(시작), End(끝), Offset(오프셋), Limit(한도)은 반환할 일치 항목의 하위 시퀀스를 정의합니다. Start(시작)와 End(끝)는 커서, Offset(오프셋)과 Limit(한도)은 정수를 취합니다. Start(시작)와 Offset(오프셋)이 첫 번째 결과에 영향을 미치고, End(끝)와 Limit(한도)은 마지막 결과에 영향을 미칩니다. Start(시작)와 Offset(오프셋)이 모두 설정된 경우 Offset(오프셋)은 Start(시작)을 기준으로 합니다. End(끝)와 Limit(한도)이 모두 설정되면 가장 빠른 제약조건이 적용됩니다. Limit(한도)는 종료가 아닌 Start+Offset(시작+오프셋)을 기준으로 합니다. 특수한 경우로, 음수 한도는 무제한을 의미합니다.

예시 코드:

type Widget struct {
    Description string
    Price       int
}

func handle(w http.ResponseWriter, r *http.Request) {
    ctx := appengine.NewContext(r)
    q := datastore.NewQuery("Widget").
        Filter("Price <", 1000).
        Order("-Price")
    b := new(bytes.Buffer)
    for t := q.Run(ctx); ; {
        var x Widget
        key, err := t.Next(&x)
        if err == datastore.Done {
            break
        }
        if err != nil {
            serveError(ctx, w, err)
            return
        }
        fmt.Fprintf(b, "Key=%v\nWidget=%#v\n\n", key, x)
    }
    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    io.Copy(w, b)
}

트랜잭션

RunInTransaction은 트랜잭션에서 함수를 실행합니다.

예시 코드:

type Counter struct {
    Count int
}

func inc(ctx context.Context, key *datastore.Key) (int, error) {
    var x Counter
    if err := datastore.Get(ctx, key, &x); err != nil && err != datastore.ErrNoSuchEntity {
        return 0, err
    }
    x.Count++
    if _, err := datastore.Put(ctx, key, &x); err != nil {
        return 0, err
    }
    return x.Count, nil
}

func handle(w http.ResponseWriter, r *http.Request) {
    ctx := appengine.NewContext(r)
    var count int
    err := datastore.RunInTransaction(ctx, func(ctx context.Context) error {
        var err1 error
        count, err1 = inc(ctx, datastore.NewKey(ctx, "Counter", "singleton", 0, nil))
        return err1
    }, nil)
    if err != nil {
        serveError(ctx, w, err)
        return
    }
    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    fmt.Fprintf(w, "Count=%d", count)
}

메타데이터

datastore 패키지를 통해 App Engine의 일부 Datastore 메타데이터에 액세스할 수 있습니다. 이 메타데이터에는 Datastore의 항목 그룹, 네임스페이스, 항목 종류, 속성, 그리고 각 속성의 속성 표현에 대한 정보가 포함됩니다.

예시 코드:

func handle(w http.ResponseWriter, r *http.Request) {
    // Print all the kinds in the datastore, with all the indexed
    // properties (and their representations) for each.
    ctx := appengine.NewContext(r)

    kinds, err := datastore.Kinds(ctx)
    if err != nil {
        serveError(ctx, w, err)
        return
    }

    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    for _, kind := range kinds {
        fmt.Fprintf(w, "%s:\n", kind)
        props, err := datastore.KindProperties(ctx, kind)
        if err != nil {
            fmt.Fprintln(w, "\t(unable to retrieve properties)")
            continue
        }
        for p, rep := range props {
            fmt.Fprintf(w, "\t-%s (%s)\n", p, strings.Join(rep, ", "))
        }
    }
}

변수

ErrInvalidEntityType, ErrInvalidKey, ErrNoSuchEntity

var (
	// ErrInvalidEntityType is returned when functions like Get or Next are
	// passed a dst or src argument of invalid type.
	ErrInvalidEntityType = errors.New("datastore: invalid entity type")
	// ErrInvalidKey is returned when an invalid key is presented.
	ErrInvalidKey = errors.New("datastore: invalid key")
	// ErrNoSuchEntity is returned when no entity was found for a given key.
	ErrNoSuchEntity = errors.New("datastore: no such entity")
)

완료

var Done = errors.New("datastore: query has no more results")

쿼리 반복이 완료되면 Done이 반환됩니다.

ErrConcurrentTransaction

var ErrConcurrentTransaction = errors.New("datastore: concurrent transaction")

동시 트랜잭션과의 충돌로 인해 트랜잭션이 롤백되면 ErrConcurrentTransaction이 반환됩니다.

함수

func AllocateIDRange

func AllocateIDRange(c context.Context, kind string, parent *Key, start, end int64) (err error)

AllocateIDRange는 특정 엔드포인트를 가진 ID 범위를 할당합니다. 이 범위는 하한 및 상한을 모두 포함합니다. 이 ID가 할당되면 새로 생성된 항목에 수동으로 할당할 수 있습니다.

Datastore의 자동 ID 할당자는 이미 (자동 ID 할당 또는 명시적 AllocateIDs 호출을 통해) 할당된 키를 절대 할당하지 않습니다. 결과적으로 주어진 키 범위에 쓰인 항목은 절대 덮어쓰게 되지 않습니다. 하지만 이 범위에 수동으로 할당된 키를 가진 항목을 쓰는 경우 반환된 오류에 따라 기존 항목(또는 별도의 요청으로 쓰인 새 항목)을 덮어쓸 수 있습니다.

예약하려는 기존 숫자 ID 범위(예: 이미 ID를 가진 일괄 로드 항목)가 있는 경우에만 사용하세요. 수신할 ID를 고려할 필요가 없으면 AllocateIDs를 대신 사용하세요.

AllocateIDRange는 범위가 성공적으로 할당되면 nil을 반환합니다. 지정된 범위에 이미 있는 ID가 하나 이상 있는 항목은 KeyRangeCollisionError를 반환합니다. Datastore가 이 범위 내 ID를 이미 캐시한 경우(예: AllocateIDRange에 대한 이전 호출) KeyRangeContentionError가 반환됩니다. 다른 유형의 오류는 인수에 대한 문제 또는 Datastore에서 직접 반환된 오류를 나타냅니다.

func AllocateIDs

func AllocateIDs(c context.Context, kind string, parent *Key, n int) (low, high int64, err error)

AllocateIDs는 지정된 kind 및 parent 조합을 가진 정수 ID n개의 범위를 반환합니다. kind는 비워 둘 수 없으며, parent는 nil일 수 있습니다. 반환된 범위 내의 ID는 datastore의 자동 ID 시퀀스 생성기에서 사용되지 않으며, NewKey와는 충돌 없이 사용할 수 있습니다.

범위의 low 값은 범위에 포함되고 high 값은 범위에 포함되지 않습니다. 즉, 유효한 intID x는 low보다는 크거나 같고 high보다는 작습니다.

오류가 반환되지 않는 경우 low + n == high입니다.

func Delete

func Delete(c context.Context, key *Key) error

Delete는 지정된 key에 해당하는 항목을 삭제합니다.

func DeleteMulti

func DeleteMulti(c context.Context, key []*Key) error

DeleteMulti는 Delete의 일괄 버전입니다.

func EnableKeyConversion

func EnableKeyConversion(ctx context.Context)

EnableKeyConversion은 Cloud Datastore 클라이언트 라이브러리(cloud.google.com/go/datastore)에서 인코딩된 키 호환성을 사용 설정합니다. Cloud Datastore 클라이언트 라이브러리에서 생성된 인코딩된 키는 App Engine Datastore 키로 디코딩됩니다.

App Engine 1세대 런타임에서 실행되는 경우 제공된 컨텍스트는 App Engine 컨텍스트여야 합니다. /_ah/start 핸들러에서 호출할 수 있습니다. 이는 여러 번 호출하는 것이 안전하며 호출 비용이 저렴하므로 미들웨어로 삽입할 수도 있습니다.

키 호환성을 사용 설정해도 Key.Encode에 사용되는 인코딩 형식에 영향을 주지 않으며 DecodeKey로 디코딩할 수 있는 키 유형만 확장됩니다.

func Get

func Get(c context.Context, key *Key, dst interface{}) error

Get은 key에 대해 저장된 항목을 dst로 로드합니다. dst는 구조체 포인터이거나 PropertyLoadSaver를 구현해야 합니다. 키에 대한 항목이 없다면 Get은 ErrNoSuchEntity를 반환합니다.

dst에서 일치하지 않는 구조체 필드의 값은 수정되지 않으며, 일치하는 슬라이스 유형 필드는 dst 필드에 추가되기 전에는 재설정되지 않습니다. 특히 각 Get 호출에서 값이 0인 구조체에 대한 포인터를 전달하는 것이 좋습니다.

저장된 것과 다른 유형으로 필드를 로드해야 하거나 대상 구조체에서 필드가 누락되거나 내보내기가 되지 않았다면 ErrFieldMismatch가 반환됩니다. ErrFieldMismatch는 dst가 구조체 포인터인 경우에만 반환됩니다.

func GetMulti

func GetMulti(c context.Context, key []*Key, dst interface{}) error

GetMulti는 Get의 일괄 버전입니다.

dst는 []S, []*S, []I 또는 []P여야 합니다. 구조체 유형의 경우 S, 인터페이스 유형의 경우 I, 인터페이스가 아니고 포인터가 아닌 유형의 경우 P이므로 P 또는 *P는 PropertyLoadSaver를 구현합니다. []I의 경우, 각 요소는 Get에 유효한 dst여야 합니다. 즉, 구조체 유형이거나 PropertyLoadSaver를 구현해야 합니다.

특수한 경우로, PropertyList는 구조체 슬라이스이더라도 dst에는 잘못된 유형입니다. []PropertyList를 사용하려는데 이를 잘못 전달하는 경우를 방지하고자 PropertyList는 잘못된 것으로 처리됩니다.

func KindProperties

func KindProperties(ctx context.Context, kind string) (map[string][]string, error)

KindProperties는 지정된 kind에 대해 색인이 생성된 모든 속성을 반환합니다. 속성은 속성 이름과 표현 유형 슬라이스의 매핑으로 반환됩니다. 지원되는 Go 속성 유형의 표현 유형은 다음과 같습니다.

"INT64":     signed integers and time.Time
"DOUBLE":    float32 and float64
"BOOLEAN":   bool
"STRING":    string, []byte and ByteString
"POINT":     appengine.GeoPoint
"REFERENCE": *Key
"USER":      (not used in the Go runtime)

func Kinds

func Kinds(ctx context.Context) ([]string, error)

Kinds는 현재 네임스페이스에 있는 모든 종류의 이름을 반환합니다.

func LoadStruct

func LoadStruct(dst interface{}, p []Property) error

LoadStruct는 p에서 dst로 필드를 로드합니다. dst는 구조체 포인터여야 합니다.

func Namespaces

func Namespaces(ctx context.Context) ([]string, error)

Namespaces는 모든 datastore 네임스페이스를 반환합니다.

func RunInTransaction

func RunInTransaction(c context.Context, f func(tc context.Context) error, opts *TransactionOptions) error

RunInTransaction은 트랜잭션에서 f를 실행합니다. 이 함수는 f가 모든 App Engine 작업에 사용해야 하는 트랜잭션 컨텍스트 tc에서 f를 실행합니다.

f가 nil을 반환하면 RunInTransaction은 트랜잭션을 커밋하려고 시도하고, 이에 성공하면 nil을 반환합니다. 충돌하는 트랜잭션으로 인해 커밋에 실패하면 RunInTransaction은 매번 새 트랜잭션 컨텍스트를 사용하여 f를 다시 시도합니다. 세 번 시도 후에도 실패하면 실행을 포기하고 ErrConcurrentTransaction을 반환합니다. 시도 횟수는 TransactionOptions.Attempts를 지정하여 구성할 수 있습니다.

f가 nil이 아닌 값을 반환하면 Datastore 변경사항이 적용되지 않으며 RunInTransaction은 동일한 오류를 반환합니다. 함수 f는 다시 시도되지 않습니다.

f가 값을 반환할 때 트랜잭션은 아직 커밋되지 않은 상태입니다. 따라서 코드 호출 시 RunInTransaction이 nil을 반환하기 전까지는 f의 모든 변경사항이 커밋된 것으로 가정하지 않도록 주의해야 합니다.

f는 여러 번 호출될 수 있으므로 일반적으로 멱등적이어야 합니다. datastore.Get은 슬라이스 필드를 역마샬링할 때는 멱등적이지 않습니다.

중첩 트랜잭션은 지원되지 않으므로 c는 트랜잭션 컨텍스트일 수 없습니다.

ByteString

type ByteString []byte

ByteString은 색인을 생성할 수 있는 짧은 바이트 슬라이스(최대 1500바이트)입니다.

Cursor

type Cursor struct {
	// contains filtered or unexported fields
}

Cursor는 반복기의 위치입니다. 불투명 문자열로 변환되거나 불투명 문자열에서 변환될 수 있습니다. 커서는 종류, 상위 항목, 필터, 순서 제약조건이 동일한 쿼리를 사용하는 경우에 한해 여러 HTTP 요청에서 사용할 수 있습니다.

func DecodeCursor

func DecodeCursor(s string) (Cursor, error)

DecodeCursor는 base-64 문자열 표현에서 커서를 디코딩합니다.

func (Cursor) String

func (c Cursor) String() string

String은 Cursor의 base-64 문자열 표현을 반환합니다.

항목

type Entity struct {
	Key        *Key
	Properties []Property
}

Entity는 중첩 구조체의 값 유형입니다. 이 유형은 속성 값에만 사용됩니다.

ErrFieldMismatch

type ErrFieldMismatch struct {
	StructType reflect.Type
	FieldName  string
	Reason     string
}

저장된 것과 다른 유형으로 필드를 로드해야 하거나 대상 구조체에서 필드가 누락되거나 내보내기가 되지 않았다면 ErrFieldMismatch가 반환됩니다. StructType은 Get 또는 Iterator.Next에 전달된 대상 인수가 가리키는 구조체의 유형입니다.

func (*ErrFieldMismatch) Error

func (e *ErrFieldMismatch) Error() string

반복자

type Iterator struct {
	// contains filtered or unexported fields
}

Iterator는 쿼리를 실행한 결과입니다.

func (*Iterator) Cursor

func (t *Iterator) Cursor() (Cursor, error)

Cursor는 반복기의 현재 위치에 대한 커서를 반환합니다.

func (*Iterator) Next

func (t *Iterator) Next(dst interface{}) (*Key, error)

Next는 다음 결과의 키를 반환합니다. 더 이상 결과가 없으면 오류로 Done이 반환됩니다.

또한 쿼리가 키 전용 쿼리가 아니고 dst가 nil이 아니면 Next는 해당 키에 대해 저장된 항목을 구조체 포인터 또는 PropertyLoadSaver dst로 로드합니다. 이때 의미 체계와 발생할 수 있는 오류는 Get 함수의 경우와 동일합니다.

키

type Key struct {
	// contains filtered or unexported fields
}

Key는 저장된 항목의 데이터 저장소 키를 나타내며 변경 불가능합니다.

func DecodeKey

func DecodeKey(encoded string) (*Key, error)

DecodeKey는 Encode로 반환된 불투명 표현에서 키를 디코딩합니다.

func NewIncompleteKey

func NewIncompleteKey(c context.Context, kind string, parent *Key) *Key

NewIncompleteKey는 새로운 불완전 키를 만듭니다. kind는 비워둘 수 없습니다.

func NewKey

func NewKey(c context.Context, kind, stringID string, intID int64, parent *Key) *Key

NewKey는 새 키를 만듭니다. kind는 비워둘 수 없습니다. stringID와 intID는 둘 중 하나 또는 둘 모두가 0이어야 합니다. 둘 다 0인 경우 반환되는 키는 불완전 키입니다. parent는 완전한 키이거나 nil이어야 합니다.

func Put

func Put(c context.Context, key *Key, src interface{}) (*Key, error)

Put은 키 k를 사용하여 항목 src를 Datastore에 저장합니다. src는 구조체 포인터이거나 PropertyLoadSaver를 구현해야 합니다. 구조체 포인터인 경우 해당 구조체의 내보내지 않은 모든 필드는 건너뜁니다. k가 불완전 키인 경우 반환되는 키는 Datastore에서 생성된 고유 키입니다.

func PutMulti

func PutMulti(c context.Context, key []*Key, src interface{}) ([]*Key, error)

PutMulti는 Put의 일괄 버전입니다.

src는 GetMulti의 dst 인수와 동일한 조건을 충족해야 합니다.

func (*Key) AppID

func (k *Key) AppID() string

AppID는 키의 애플리케이션 ID를 반환합니다.

func (*Key) Encode

func (k *Key) Encode() string

Encode는 HTML과 URL에서 사용하기에 적합한 키의 불투명 표현을 반환합니다. 이 함수는 Python 및 자바 런타임과 호환됩니다.

func (*Key) Equal

func (k *Key) Equal(o *Key) bool

Equal은 두 개의 키가 같은지의 여부를 반환합니다.

func (*Key) GobDecode

func (k *Key) GobDecode(buf []byte) error

func (*Key) GobEncode

func (k *Key) GobEncode() ([]byte, error)

func (*Key) Incomplete

func (k *Key) Incomplete() bool

Incomplete는 키가 저장된 항목을 참조하지 않는지 여부를 반환합니다. 특히 키의 StringID가 0이고 IntID가 0인지 여부를 반환합니다.

func (*Key) IntID

func (k *Key) IntID() int64

IntID는 키의 정수 ID를 반환하며, 이 ID는 0일 수 있습니다.

func (*Key) Kind

func (k *Key) Kind() string

Kind는 키의 종류(항목 유형이라고도 함)를 반환합니다.

func (*Key) MarshalJSON

func (k *Key) MarshalJSON() ([]byte, error)

func (*Key) Namespace

func (k *Key) Namespace() string

Namespace는 키의 네임스페이스를 반환합니다.

func (*Key) Parent

func (k *Key) Parent() *Key

Parent는 키의 상위 키를 반환하며, 이 키는 nil일 수 있습니다.

func (*Key) String

func (k *Key) String() string

String은 키의 문자열 표현을 반환합니다.

func (*Key) StringID

func (k *Key) StringID() string

StringID는 키의 문자열 ID(항목 이름 또는 키 이름이라고도 함)을 반환하며, 이 ID는 ""일 수 있습니다.

func (*Key) UnmarshalJSON

func (k *Key) UnmarshalJSON(buf []byte) error

KeyRangeCollisionError

type KeyRangeCollisionError struct {
	// contains filtered or unexported fields
}

func (*KeyRangeCollisionError) 오류

func (e *KeyRangeCollisionError) Error() string

KeyRangeContentionError

type KeyRangeContentionError struct {
	// contains filtered or unexported fields
}

func (*KeyRangeContentionError) 오류

func (e *KeyRangeContentionError) Error() string

속성

type Property struct {
	// Name is the property name.
	Name string
	// Value is the property value. The valid types are:
	//	- int64
	//	- bool
	//	- string
	//	- float64
	//	- ByteString
	//	- *Key
	//	- time.Time
	//	- appengine.BlobKey
	//	- appengine.GeoPoint
	//	- []byte (up to 1 megabyte in length)
	//	- *Entity (representing a nested struct)
	// This set is smaller than the set of valid struct field types that the
	// datastore can load and save. A Property Value cannot be a slice (apart
	// from []byte); use multiple Properties instead. Also, a Value's type
	// must be explicitly on the list above; it is not sufficient for the
	// underlying type to be on that list. For example, a Value of "type
	// myInt64 int64" is invalid. Smaller-width integers and floats are also
	// invalid. Again, this is more restrictive than the set of valid struct
	// field types.
	//
	// A Value will have an opaque type when loading entities from an index,
	// such as via a projection query. Load entities into a struct instead
	// of a PropertyLoadSaver when using a projection query.
	//
	// A Value may also be the nil interface value; this is equivalent to
	// Python's None but not directly representable by a Go struct. Loading
	// a nil-valued property into a struct will set that field to the zero
	// value.
	Value interface{}
	// NoIndex is whether the datastore cannot index this property.
	NoIndex bool
	// Multiple is whether the entity can have multiple properties with
	// the same name. Even if a particular instance only has one property with
	// a certain name, Multiple should be true if a struct would best represent
	// it as a field of type []T instead of type T.
	Multiple bool
}

Property는 이름/값 쌍과 일부 메타데이터입니다. Datastore 항목의 내용은 일련의 Property로 로드되고 저장됩니다. 하나의 항목에는 동일한 이름의 여러 속성이 있을 수 있습니다. 단, 해당 항목에서 동일한 이름의 모든 속성에 대해 p.Multiple이 true여야 합니다.

func SaveStruct

func SaveStruct(src interface{}) ([]Property, error)

SaveStruct는 src의 속성을 속성 슬라이스로 반환합니다. src는 구조체 포인터여야 합니다.

PropertyList

type PropertyList []Property

PropertyList는 []Property를 변환하여 PropertyLoadSaver를 구현합니다.

func (*PropertyList) Load

func (l *PropertyList) Load(p []Property) error

Load는 제공된 모든 속성을 l로 로드합니다. 이 함수는 먼저 *l를 빈 슬라이스로 재설정하지 않습니다.

func (*PropertyList) Save

func (l *PropertyList) Save() ([]Property, error)

Save는 l의 모든 속성을 하나의 슬라이스 또는 여러 속성으로 저장합니다.

PropertyLoadSaver

type PropertyLoadSaver interface {
	Load([]Property) error
	Save() ([]Property, error)
}

PropertyLoadSaver는 속성 슬라이스에서 변환되거나 속성 슬라이스로 변환될 수 있습니다.

쿼리

type Query struct {
	// contains filtered or unexported fields
}

Query는 데이터 저장소 쿼리를 나타냅니다.

func NewQuery

func NewQuery(kind string) *Query

NewQuery는 특정 항목 종류에 대한 새 쿼리를 만듭니다.

kind가 비어 있으면 다른 App Engine 기능으로 생성 및 관리되는 항목을 비롯한 모든 항목이 반환되며, 이러한 쿼리를 비구분 쿼리라고 합니다. 비구분 쿼리는 속성 값에 필터나 정렬 순서를 포함할 수 없습니다.

func (*Query) Ancestor

func (q *Query) Ancestor(ancestor *Key) *Query

Ancestor는 상위 필터가 있는 파생 쿼리를 반환합니다. ancestor는 nil이 아니어야 합니다.

func (*Query) BatchSize

func (q *Query) BatchSize(size int) *Query

BatchSize는 파생 쿼리를 반환하여 제공된 결과 수를 한 번에 가져옵니다. 이 값은 0보다 커야 하고 제한보다 작거나 같아야 합니다.

func (*Query) Count

func (q *Query) Count(c context.Context) (int, error)

Count는 쿼리 결과의 수를 반환합니다.

Count에 의해 실행되는 API 호출의 실행 시간과 호출 횟수는 쿼리 오프셋 및 제한의 합에 따라 선형적으로 확장됩니다. 결과 수가 적을 것으로 예상되는 경우가 아니라면 제한을 지정하는 것이 좋습니다. 그렇지 않으면 개수 계산이 끝나거나 지정된 컨텍스트가 만료될 때까지 Count가 계속 실행됩니다.

func (*Query) Distinct

func (q *Query) Distinct() *Query

Distinct는 프로젝션된 필드 집합에 대해 중복되지 않는 항목을 생성하는 파생 쿼리를 반환합니다. 이 함수는 프로젝션 쿼리에만 사용됩니다. Distinct는 DistinctOn과 함께 사용할 수 없습니다.

func (*Query) DistinctOn

func (q *Query) DistinctOn(fieldNames string) *Query

DistinctOn은 지정된 필드 집합에 대해 중복되지 않는 항목을 생성하는 파생 쿼리를 반환합니다. 이 함수는 프로젝션 쿼리에만 사용됩니다. 필드 목록은 프로젝션된 필드 목록의 하위 집합이어야 합니다. DistinctOn은 Distinct와 함께 사용할 수 없습니다.

func (*Query) End

func (q *Query) End(c Cursor) *Query

End는 지정된 엔드포인트를 사용하는 파생 쿼리를 반환합니다.

func (*Query) EventualConsistency

func (q *Query) EventualConsistency() *Query

EventualConsistency는 최종 일관성이 있는 결과를 반환하는 파생 쿼리를 반환합니다. 이 함수는 상위 쿼리에만 적용됩니다.

func (*Query) Filter

func (q *Query) Filter(filterStr string, value interface{}) *Query

Filter는 필드 기반 필터를 사용하는 파생 쿼리를 반환합니다. filterStr 인수는 필드 이름으로, 그 뒤에 선택적 공백과 '>', '<', '>=', '<=' 또는 '=' 연산자 중 하나가 차례로 와야 합니다. 필드는 연산자를 사용하여 제공된 값과 비교됩니다. 여러 개의 필터가 AND 연산됩니다.

func (*Query) GetAll

func (q *Query) GetAll(c context.Context, dst interface{}) ([]*Key, error)

GetAll은 지정된 컨텍스트에서 쿼리를 실행한 후 해당 쿼리와 일치하는 모든 키를 반환하고 해당 값을 dst에 추가합니다.

dst는 []S, *[]S 또는 *[]P여야 합니다. 구조체 유형의 경우 S, 인터페이스가 아니고 포인터가 아닌 유형의 경우 P이므로 P 또는 *P는 PropertyLoadSaver를 구현합니다.

특수한 경우로, PropertyList가 구조체 슬라이스이더라도 *PropertyList는 dst에는 잘못된 유형입니다. *[]PropertyList를 사용하려는데 이를 잘못 전달하는 경우를 방지하기 위해 *PropertyList는 잘못된 것으로 처리됩니다.

GetAll이 반환하는 키는 dst에 추가되는 항목과 일대일로 대응합니다.

q가 '키 전용' 쿼리인 경우 GetAll은 dst를 무시하고 키만 반환합니다.

GetAll에 의해 실행되는 API 호출의 실행 시간과 호출 횟수는 쿼리 오프셋 및 제한의 합에 따라 선형적으로 확장됩니다. 결과 수가 적을 것으로 예상되는 경우가 아니라면 제한을 지정하는 것이 좋습니다. 그렇지 않으면 결과 수집이 끝나거나 지정된 컨텍스트가 만료될 때까지 GetAll이 계속 실행됩니다.

func (*Query) KeysOnly

func (q *Query) KeysOnly() *Query

KeysOnly는 키와 항목을 생성하는 것이 아니라 키만 생성하는 파생 쿼리를 반환합니다. 이 함수는 프로젝션 쿼리와 함께 사용할 수 없습니다.

func (*Query) Limit

func (q *Query) Limit(limit int) *Query

Limit는 반환되는 결과 수에 제한이 있는 파생 쿼리를 반환합니다. 음수 값은 무제한을 의미합니다.

func (*Query) Offset

func (q *Query) Offset(offset int) *Query

Offset은 결과를 반환하기 전에 건너뛸 키의 개수에 대한 오프셋을 사용하는 파생 쿼리를 반환합니다. 음수 값은 사용할 수 없습니다.

func (*Query) Order

func (q *Query) Order(fieldName string) *Query

Order는 필드 기반 정렬 순서를 사용하는 파생 쿼리를 반환합니다. Order는 추가된 순서대로 적용됩니다. 기본 순서는 오름차순입니다. 내림차순으로 정렬하려면 fieldName 앞에 빼기 기호(-)를 붙입니다.

func (*Query) Project

func (q *Query) Project(fieldNames string) *Query

Project는 지정된 필드만 생성하는 파생 쿼리를 반환합니다. 이 함수는 KeysOnly와 함께 사용할 수 없습니다.

func (*Query) Run

func (q *Query) Run(c context.Context) *Iterator

Run은 지정된 컨텍스트에서 쿼리를 실행합니다.

func (*Query) Start

func (q *Query) Start(c Cursor) *Query

Start는 지정된 시작점을 사용하는 파생 쿼리를 반환합니다.

TransactionOptions

type TransactionOptions struct {
	// XG is whether the transaction can cross multiple entity groups. In
	// comparison, a single group transaction is one where all datastore keys
	// used have the same root key. Note that cross group transactions do not
	// have the same behavior as single group transactions. In particular, it
	// is much more likely to see partially applied transactions in different
	// entity groups, in global queries.
	// It is valid to set XG to true even if the transaction is within a
	// single entity group.
	XG bool
	// Attempts controls the number of retries to perform when commits fail
	// due to a conflicting transaction. If omitted, it defaults to 3.
	Attempts int
	// ReadOnly controls whether the transaction is a read only transaction.
	// Read only transactions are potentially more efficient.
	ReadOnly bool
}

TransactionOptions는 트랜잭션을 실행하기 위한 옵션입니다.