パッケージ google.golang.org/appengine/datastore(v1.6.8)

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

基本オペレーション

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

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

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

  • 符号付き整数(int、int8、int16、int32、int64)
  • bool、
  • string、
  • float32 と float64、
  • []byte(最大長: 1 メガバイト)
  • 基になる型が上記で宣言された型のいずれかであるすべての型、
  • ByteString、
  • *Key、
  • time.Time(マイクロ秒精度で格納)、
  • appengine.BlobKey、
  • appengine.GeoPoint、
  • フィールドがすべて有効な値の型である構造体、
  • 上記のいずれかのスライス。

構造体のスライス、スライスを含む構造体のいずれも有効です。しかし、ある構造体に別の構造体が含まれている場合、その繰り返しは 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 呼び出しの間、または異なるデータストアへの呼び出しの間で一致する必要はありません。*PropertyList を保存して、同じエンティティを *myStruct として取得することや、*myStruct0 を保存して、*myStruct1 を取得することは有効です。概念的には、エンティティは一連のプロパティとして保存され、プロパティごとに参照先の値に読み込まれます。エンティティを構造体ポインタに読み込んだときに、完全に表現できないエンティティ(フィールドの欠落など)は ErrFieldMismatch エラーになりますが、このエラーが致命的か、回復可能か、無視できるかは呼び出し元によって異なります。

構造体ポインタの場合、デフォルトではすべてのプロパティにインデックスが付けられる可能性があり、プロパティ名はフィールド名と同じです(したがって、先頭を大文字にする必要があります)。

フィールドに datastore:"name,options" タグを含めることができます。このタグ名はプロパティ名であり、"." で結合された 1 つ以上の有効な Go 識別子である必要がありますが、先頭を小文字にできます。空のタグ名は、フィールド名を使用することを意味します。"-" というタグ名は、データストアがそのフィールドを無視することを意味します。

有効なオプションは「omitempty」と「noindex」のみです。

オプションに「omitempty」が含まれていて、フィールドの値が空の場合、そのフィールドは保存時に省略されます。空の値は、false、0、nil インターフェース値、長さ 0 の任意の配列、スライス、マップ、文字列です。構造体フィールドの値が空になることはありません。

オプションが "noindex" の場合、そのフィールドにインデックスは付けられません。デフォルトでは、すべてのフィールドのインデックスが作成されます。1,500 バイトを超える文字列またはバイトスライスはインデックスに登録できません。長い文字列やバイトスライスの格納に使用されるフィールドには、"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" になります。

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 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 を実装しているため、任意のエンティティの内容を保持できます。

クエリ

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

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

  • 祖先とフィルタは、クエリの実行によって返されるエンティティに制約を設定します。
  • 順序は、返される順序に影響します。
  • プロジェクトは、返されるフィールドを制限します。
  • 射影されたエンティティの重複を排除します。
  • KeysOnly は、イテレータが(key、entity)ペアではなく、キーのみを返すようにします。
  • Start、End、Offset、Limit は、一致するエンティティのどのサブシーケンスを返すかを定義します。Start と End はカーソルを、Offset と Limit は整数を取ります。Start と Offset は最初の結果に影響し、End と Limit は最後の結果に影響します。Start と Offset の両方を設定した場合、オフセットは Start に対する相対的なものになります。End と Limit の両方を設定した場合は、最も早い制約が優先されます。制限は、End を基準とするのではなく、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 のデータストア メタデータの一部にアクセスできます。このメタデータには、データストア内のエンティティ グループ、名前空間、エンティティの種類、プロパティに関する情報と、各プロパティのプロパティ表現が含まれています。

コードの例:

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

Done

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 が割り当てられると、新しく作成したエンティティに ID を手動で割り当てることができます。

Datastore の自動 ID 割り当てツールは、ID の自動割り当てまたは明示的な AllocateIDs 呼び出しで割り当て済みのキーを割り当てません。このため、特定のキー範囲に書き込まれたエンティティが上書きされることはありません。ただし、この範囲に手動で割り当てたキーのエンティティを作成すると、返されたエラーに応じて、既存のエンティティ(または、別のリクエストによって作成された新しいエンティティ)が上書きされる場合があります。

この関数は、予約する数値 ID 範囲が存在する場合にだけ利用してください(たとえば、ID のあるエンティティを一括で読み込む場合など)。受信する ID を確認する必要がない場合には、AllocateIDs を使用してください。

範囲が正常に割り当てられた場合、AllocateIDRange は nil を返します。指定された範囲内の ID を持つエンティティが 1 つ以上存在する場合は、KeyRangeCollisionError が返されます。この範囲内の ID がすでに Datastore のキャッシュに保存されている場合(以前の AllocateIDRange の呼び出しなど)、KeyRangeContentionError が返されます。他のタイプのエラーは、引数に関する問題か、Datastore から直接返されたエラーを示します。

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 EnableKeyConversion

func EnableKeyConversion(ctx context.Context)

EnableKeyConversion により、エンコードされた鍵と Cloud Datastore クライアント ライブラリ(cloud.google.com/go/datastore)との互換性が確保されます。Cloud Datastore クライアント ライブラリによって生成されたエンコードされたキーは、App Engine データストアのキーにデコードされます。

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 を実装している必要があります。key にそのようなエンティティがない場合、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 のつもりで誤って渡されるのを避けるため、無効として扱われます。

func 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 は、f から dst までのプロパティを読み込みます。dst は構造体ポインタである必要があります。

func Namespaces

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

Namespaces は、すべてのデータストア名前空間を返します。

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 がトランザクション コンテキストではない可能性があります)。

ByteString

type ByteString []byte

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

Cursor

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

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

func DecodeCursor

func DecodeCursor(s string) (Cursor, error)

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

func (Cursor) String

func (c Cursor) String() string

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

Entity

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

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 関数と同じです。

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 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 (*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 は、キーが格納されているエンティティを参照していないかどうか(特に、キーが 0 の StringID と 0 の 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

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

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 の場合に限ります。

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

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

func (*PropertyList) Save

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

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

PropertyLoadSaver

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

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

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) 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 は、射影されたフィールドのセットに関して重複が排除されたエンティティを生成する派生クエリを返します。これは射影クエリでのみ使用されます。DistinctOn では Distinct を使用できません。

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

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

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 は、トランザクションの実行に関するオプションです。