datastore パッケージ

import "google.golang.org/appengine/datastore"

はじめに

Datastore パッケージは、App Engine のデータストア サービス用のクライアントを提供します。

基本オペレーション

エンティティは、ストレージの単位であり、1 つのキーに関連付けられています。キーは、オプションの親キー、文字列のアプリケーション ID、文字列の種類(エンティティ タイプとも呼ばれます)、および StringID または IntID のいずれかで構成されます。StringID はエンティティ名またはキー名とも呼ばれます。

ゼロの StringID とゼロの IntID を含むキーを作成することは有効です。これは不完全キーと呼ばれ、保存されているエンティティを参照しません。不完全キーを使用してデータストアにエンティティを保存すると、そのエンティティに対してゼロ以外の IntID を含む固有のキーが生成されます。

エンティティの内容は、大文字と小文字を区別するフィールド名から値へのマッピングです。有効な値の型は次のとおりです。

- signed integers (int, int8, int16, int32 and int64),
- bool,
- string,
- float32 and float64,
- []byte (up to 1 megabyte in length),
- any type whose underlying type is one of the above predeclared types,
- ByteString,
- *Key,
- time.Time (stored with microsecond precision),
- appengine.BlobKey,
- appengine.GeoPoint,
- structs whose fields are all valid value types,
- slices of any of the above.

構造体のスライス、スライスを含む構造体のいずれも有効です。しかし、ある構造体に別の構造体が含まれている場合、その繰り返しは 1 回だけに限られます。このため、再帰的に定義された構造体型、つまり、[]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 インターフェースを実装する任意の型にすることもできます。構造体ポインタを使用する場合は、PropertyLoadSaver インターフェースを明示的に実装する必要はありません。データストアはリフレクションによって自動的に変換されます。構造体ポインタがこのインターフェースを実装している場合は、それらのメソッドが構造体ポインタのデフォルトの動作よりも優先して使用されます。構造体ポインタはより厳密に型指定され、使いやすいのに対して、PropertyLoadSaver はより柔軟に使用できます。

実際に渡される型は、Get 呼び出しと Put 呼び出しの間、または異なる App Engine リクエストの間で一致する必要はありません。*PropertyList を保存し、同じエンティティを *myStruct として取得したり、*myStruct0 を保存し、*myStruct1 を取得したりすることは有効です。概念的には、エンティティは一連のプロパティとして保存され、プロパティごとに参照先の値に読み込まれます。エンティティを構造体ポインタに読み込んだときに、完全に表現できないエンティティ(フィールドの欠落など)は ErrFieldMismatch エラーになりますが、このエラーが致命的か、回復可能か、無視できるかは呼び出し元によって異なります。

構造体ポインタの場合、デフォルトではすべてのプロパティにインデックスが付けられる可能性があり、プロパティ名はフィールド名と同じです(したがって、先頭を大文字にする必要があります)。フィールドに `datastore:"name,options"` タグを付けることもできます。このタグ名はプロパティ名であり、"." で結合された 1 つ以上の有効な Go 識別子である必要がありますが、先頭を小文字にすることができます。空のタグ名は、フィールド名を使用することを意味します。"-" というタグ名は、データストアがそのフィールドを無視することを意味します。オプションが "noindex" の場合、そのフィールドにインデックスは付けられません。オプションが "" の場合、カンマは省略できます。その他に認識されるオプションはありません。

フィールド([]byte を除く)には、デフォルトでインデックスが付けられます。1,500 バイトを超える文字列にインデックスを付けることはできません。長い文字列を格納するフィールドには、"noindex" というタグを付ける必要があります。同様に、1,500 バイトを超える ByteString にもインデックスを付けることはできません。

サンプルコード:

// 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"` になります。

Outer 構造体に "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 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),
        },
    }
}

*PropertyList 型は PropertyLoadSaver を実装しているため、任意のエンティティの内容を保持できます。

クエリ

クエリは、エンティティのプロパティまたはキーの祖先に基づいてエンティティを取得します。クエリを実行すると、結果(キーまたはキーとエンティティのペアのいずれか)のイテレータが生成されます。クエリは再利用可能であり、同時実行の Go ルーチンから Query.Run を安全に呼び出すことができます。イテレータの同時使用は安全ではありません。

クエリは不変であり、NewQuery の呼び出しによって作成するか、または新しいクエリ値を返す Filter や Order のようなメソッドを呼び出すことによって既存のクエリから派生します。クエリは、通常、NewQuery を呼び出した後、このようなメソッドを連続して 0 個以上呼び出すことで作成されます。次のようなメソッドを使用できます。

- Ancestor and Filter constrain the entities returned by running a query.
- Order affects the order in which they are returned.
- Project constrains the fields returned.
- Distinct de-duplicates projected entities.
- KeysOnly makes the iterator return only keys, not (key, entity) pairs.
- Start, End, Offset and Limit define which sub-sequence of matching entities
  to return. Start and End take cursors, Offset and Limit take integers. Start
  and Offset affect the first result, End and Limit affect the last result.
  If both Start and Offset are set, then the offset is relative to Start.
  If both End and Limit are set, then the earliest constraint wins. Limit is
  relative to Start+Offset, not relative to End. As a special case, a
  negative limit means unlimited.

サンプルコード:

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 のデータストア メタデータの一部にアクセスできます。このメタデータには、データストア内のエンティティ グループ、名前空間、エンティティの種類、プロパティに関する情報と、各プロパティのプロパティ表現が含まれています。

サンプルコード:

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))
        }
    }
}

インデックス

変数
func AllocateIDs(c context.Context, kind string, parent *Key, n int) (low, high int64, err error)
func Delete(c context.Context, key *Key) error
func DeleteMulti(c context.Context, key []*Key) error
func Get(c context.Context, key *Key, dst interface{}) error
func GetMulti(c context.Context, key []*Key, dst interface{}) error
func KindProperties(ctx context.Context, kind string) (map[string][]string, error)
func Kinds(ctx context.Context) ([]string, error)
func LoadStruct(dst interface{}, p []Property) error
func Namespaces(ctx context.Context) ([]string, error)
func Put(c context.Context, key *Key, src interface{}) (*Key, error)
func PutMulti(c context.Context, key []*Key, src interface{}) ([]*Key, error)
func RunInTransaction(c context.Context, f func(tc context.Context) error, opts *TransactionOptions) error
func SaveStruct(src interface{}) ([]Property, error)
type ByteString
type Cursor
    func DecodeCursor(s string) (Cursor, error)
    func (c Cursor) String() string
type Entity
type ErrFieldMismatch
    func (e *ErrFieldMismatch) Error() string
type Iterator
    func (t *Iterator) Cursor() (Cursor, error)
    func (t *Iterator) Next(dst interface{}) (*Key, error)
type Key
    func DecodeKey(encoded string) (*Key, error)
    func NewIncompleteKey(c context.Context, kind string, parent *Key) *Key
    func NewKey(c context.Context, kind, stringID string, intID int64, parent *Key) *Key
    func (k *Key) AppID() string
    func (k *Key) Encode() string
    func (k *Key) Equal(o *Key) bool
    func (k *Key) GobDecode(buf []byte) error
    func (k *Key) GobEncode() ([]byte, error)
    func (k *Key) Incomplete() bool
    func (k *Key) IntID() int64
    func (k *Key) Kind() string
    func (k *Key) MarshalJSON() ([]byte, error)
    func (k *Key) Namespace() string
    func (k *Key) Parent() *Key
    func (k *Key) String() string
    func (k *Key) StringID() string
    func (k *Key) UnmarshalJSON(buf []byte) error
type Property
type PropertyList
    func (l *PropertyList) Load(p []Property) error
    func (l *PropertyList) Save() ([]Property, error)
type PropertyLoadSaver
type Query
    func NewQuery(kind string) *Query
    func (q *Query) Ancestor(ancestor *Key) *Query
    func (q *Query) Count(c context.Context) (int, error)
    func (q *Query) Distinct() *Query
    func (q *Query) End(c Cursor) *Query
    func (q *Query) EventualConsistency() *Query
    func (q *Query) Filter(filterStr string, value interface{}) *Query
    func (q *Query) GetAll(c context.Context, dst interface{}) ([]*Key, error)
    func (q *Query) KeysOnly() *Query
    func (q *Query) Limit(limit int) *Query
    func (q *Query) Offset(offset int) *Query
    func (q *Query) Order(fieldName string) *Query
    func (q *Query) Project(fieldNames ...string) *Query
    func (q *Query) Run(c context.Context) *Iterator
    func (q *Query) Start(c Cursor) *Query
type TransactionOptions

変数

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 は、クエリの反復が完了したときに返されます。

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

ErrConcurrentTransaction は、同時実行トランザクションとの競合のためにトランザクションがロールバックされたときに返されます。

func AllocateIDs

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

AllocateIDs は、指定された kind と parent の組み合わせを持つ n 個の整数 ID の範囲を返します。kind を空にすることはできません。parent を nil にすることはできます。返された範囲の ID は、データストアの自動 ID シーケンス ジェネレータによって使用されず、NewKey で競合を心配せずに使用できます。

この範囲は、下限側で境界値を含み、上限側で境界値を含みません。つまり、有効な intID x は、low <= x && x < high を満たしています。

エラーが返されない場合、low + n == high になります。

func Delete

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

Delete は、指定されたキーに対応するエンティティを削除します。

func DeleteMulti

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

DeleteMulti は、Delete のバッチ バージョンです。

func Get

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

Get は、key に対応して格納されたエンティティを dst に読み込みます。dst は、構造体ポインタであるか、PropertyLoadSaver を実装している必要があります。キーにそのようなエンティティがない場合、Get は ErrNoSuchEntity を返します。

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 のつもりで誤って渡されるのを避けるため、無効として扱われます。

find KindProperties

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

KindProperties は、指定された種類のすべてのインデックス付きプロパティを返します。これらのプロパティは、表現型のスライスに対するプロパティ名のマップとして返されます。サポートされている 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 は、すべてのデータストア名前空間を返します。

func Put

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

Put は、エンティティ src をキー k でデータストアに保存します。src は構造体ポインタであるか、PropertyLoadSaver を実装している必要があります。構造体ポインタである場合は、その構造体のエクスポートされないフィールドがスキップされます。k が不完全キーである場合、返されるキーはデータストアによって生成された一意のキーになります。

func PutMulti

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

PutMulti は、Put のバッチ バージョンです。

src は GetMulti の dst 引数と同じ条件を満たしている必要があります。

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 はトランザクションを commit しようとし、成功した場合は nil を返します。競合するトランザクションのために commit が失敗した場合、RunInTransaction は毎回新しいトランザクション コンテキストで f を再試行します。試行が 3 回失敗すると、試行を中止して ErrConcurrentTransaction を返します。試行回数は、TransactionOptions.Attempts を指定することで構成できます。

f が nil 以外を返すと、データストアの変更は適用されず、RunInTransaction は同じエラーを返します。関数 f は再試行されません。

f から戻ったときに、トランザクションがまだ commit されていないことに注意してください。呼び出し側のコードは、RunInTransaction が nil を返すまでは f の変更が commit されたことを想定しないように注意する必要があります。

f は複数回呼び出すことができるため、通常、f はべき等である必要があります。datastore.Get は、スライス フィールドをマーシャリング解除するときにべき等ではありません。

ネストされたトランザクションはサポートされていません(c がトランザクション コンテキストではない可能性があります)。

func SaveStruct

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

SaveStruct は、src のプロパティをプロパティのスライスとして返します。src は構造体ポインタである必要があります。

type ByteString

type ByteString []byte

ByteString は、インデックスを付けることができる短いバイトスライス(最大 1,500 バイト)です。

type Cursor

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

カーソルはイテレータの位置です。カーソルを不透明な文字列に変換できます。また、その文字列をカーソルに変換できます。1 つのカーソルを異なる HTTP リクエストから使用できますが、その場合は同じ種類、祖先、フィルタ、順序の制約を持つクエリとともに使用する必要があります。

func DecodeCursor

func DecodeCursor(s string) (Cursor, error)

Decode は、カーソルをその Base-64 文字列表現からデコードします。

func (Cursor) String

func (c Cursor) String() string

String は、カーソルの Base-64 文字列表現を返します。

type Entity

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

Entity は、ネストされた構造体の値の型です。この型はプロパティの値にのみ使用されます。

type 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

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 でない場合は、そのキーに対応して格納されたエンティティを構造体ポインタまたは PropertyLoadSaver dst に読み込みます。この場合のセマンティクスと発生する可能性があるエラーは、Get 関数と同じです。

type Key

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 の一方または両方がゼロである必要があります。両方がゼロの場合、返されるキーは不完全です。parent は完全キーまたは nil である必要があります。

func (*Key) AppID

func (k *Key) AppID() string

AppID は、キーのアプリケーション ID を返します。

func (*Key) Encode

func (k *Key) Encode() string

Encode は、HTML と URL で使用するのに適したキーの不透明表現を返します。これは、Python と Java のランタイムと互換性があります。

func (*Key) Equal

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

Equal は、2 つのキーが等しいかどうかを返します。

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 とゼロの IntID を持つかどうか)を返します。

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

type Property

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 は、名前と値のペアにいくつかのメタデータを加えたものです。データストア エンティティの内容は、プロパティのシーケンスとして読み込まれ、保存されます。エンティティの同じ名前を持つすべてのプロパティで p.Multiple が true であれば、そのエンティティは同じ名前のプロパティを複数個持つことができます。

type PropertyList

type PropertyList []Property

PropertyList は、[]Property を変換して PropertyLoadSaver を実装します。

func (*PropertyList) Load

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

指定されたすべてのプロパティを l に読み込みます。*l は事前に空のスライスにリセットされません。

func (*PropertyList) Save

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

Save は l のすべてのプロパティをスライスまたはプロパティとして保存します。

type PropertyLoadSaver

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

PropertyLoadSaver は、プロパティのスライスとの間で変換できます。

type Query

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) Count

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

Count は、クエリの結果の数を返します。

Count によって実行された API 呼び出しの実行時間と数は、クエリのオフセットと制限の合計に比例します。結果の件数が少ないと思われる場合を除き、制限を指定するようにしてください。指定しない場合、Count は件数のカウントが完了するか、指定されたコンテキストが期限切れになるまで続行されます。

func (*Query) Distinct

func (q *Query) Distinct() *Query

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 のつもりで誤って渡されるのを避けるため、無効として扱われます。

GetAll によって返されるキーは、dst に追加されたエンティティと 1 対 1 で対応します。

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 は、指定された開始点を持つ派生クエリを返します。

type 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
}

TransactionOptions は、トランザクションの実行に関するオプションです。

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

Go の App Engine スタンダード環境