2009/05/09

Datastore Java API Overview

だらだら翻訳。かなり適当なので原文をあたってください。

Datastore Java API Overview

The Google App Engine datastore provides robust scalable data storage for your web application. The datastore is designed with web applications in mind, with an emphasis on read and query performance. It stores data entities with properties, organized by application-defined kinds. It can perform queries over entities of the same kind, with filters and sort orders on property values and keys. All queries are pre-indexed for fast results over very large data sets. The datastore supports transactional updates, using entity groupings defined by the application as the unit of transactionality in the distributed data network.

Google App Engine datastore はあなたのWebアプリケーションに堅牢でスケーラブルなデータストレージを提供します。datastoreはWebアプリケーションを念頭においてデザインされており、読み込みとクエリのパフォーマンスを重要視しています。datastoreでは、アプリケーションで定義するように構成された、エンティティとプロパティを保存します。datastoreでは、同種のエンティティ上で、プロパティの値やキーに対してフィルタ、順序のソートといったクエリを実行することができます。巨大なデータセットから高速に結果を取得するため、全てのクエリは事前にインデクシングされます。datastoreは、分散データネットワーク内で、トランザクション単位として、アプリケーションによってい定義されたエンティティグルーピングを使い、トランザクションを使った更新をサポートします。

Introducing the Datastore

The App Engine datastore stores and performs queries over data objects, known as entities. An entity has one or more properties, named values of one of several supported data types. A property can be a reference to another entity.

App Engine datastore はエンティティとして知られるデータオブジェクトを、保存しクエリーを実行します。エンティティは、いくつかのサポートされたデータ型の一つの値である名前付けられた、プロパティを一つ以上もちます。プロパティは他のエンティティへの参照ももてます。

The datastore can execute multiple operations in a single transaction, and roll back the entire transaction if any of the operations fail. This is especially useful for distributed web applications, where multiple users may be accessing or manipulating the same data object at the same time.

datastore は一つのトランザクションで複数のオペレーションを実行することができ、もしいずれかのオペレーションが失敗した場合は、トランザクション全体をロールバックすることができます。これは複数のユーザが同じデータオブジェクトに対して同時にアクセスや操作を行う、分散Webアプリケーションで特に役に立ちます。

Unlike traditional databases, the datastore uses a distributed architecture to manage scaling to very large data sets. An App Engine application can optimize how data is distributed by describing relationships between data objects, and by defining indexes for queries.

伝統的なデータベースと異なり、datastoreはとても巨大なデータセットにスケールするために分散アーキテクチャを使用しています。App Engineアプリケーションは、データオブジェクト間のリレーションシップを記述したり、クエリ用のインデックスを定義することによって、どのようにデータを分散させるかを最適化することができます。

The App Engine datastore is strongly consistent, but it's not a relational database. While the datastore interface has many of the same features of traditional databases, the datastore's unique characteristics imply a different way of designing and managing data to take advantage of the ability to scale automatically.

App Engine datastoreはとても一貫的ですが、リレーショナルデータベースではありません。Datastoreのインタフェースは伝統的なデータベースと同じものを数多く持ちながら、Datastoreの異なったデザインや自動的にスケールするための利点であるデータ管理といったユニークな特性をほのめかします。

Java Data Interfaces

Datastore entities are schemaless: Two entities of the same kind are not obligated to have the same properties, or use the same value types for the same properties. The application is responsible for ensuring that entities conform to a schema when needed. The Java SDK includes implementations of the Java Data Objects (JDO) and Java Persistence API (JPA) interfaces for modeling and persisting data. These standard interfaces include mechanisms for defining classes for data objects, and for performing queries. The datastore also provides a low-level API, which you can use to implement other interface adapters, or just use directly in your applications.

Datastore のエンティティはスキーマレスです。同じ種類の2つのエンティティは、同じプロパティを持つ必要がありません。また、同じプロパティに同じデータ型を持つ必要もありません。アプリケーションは必要に応じて、エンティティのスキーマを確認する責任があります。Java SDKは、データのモデリングと、永続化のためにJava Data Objects (JDO) と Java Persistence API (JPA)の実装を持っています。これらの標準インターフェースはデータオブジェクトのクラス定義と、クエリ実行の仕組みを含んでいます。また、あなたのアプリケーションで他のインターフェースアダプタを実装したり、直接アクセスするための低レベルAPIをDatastoreは提供します。

This documentation describes JDO in detail. Most other sources of information about JDO also apply to App Engine. Please refer to the documentation in this guide for information about implementation differences and unimplemented features.

このドキュメントではJDOについて詳細に記述しています。JDOに関するほかの情報の大部分もまた、App Engineで使うことができます。実装の差異や未実装の機能についての情報は、このガイドを参照してください。

JPA is also supported. This documentation describes JPA briefly; see Using JPA.

JPAもまたサポートしています。このドキュメントでは、Using JPAでJPAについて簡潔に記述しています。

JDO uses annotations on Java classes ("plain old Java objects," or "POJOs") to describe how instances of the class are stored in the datastore as entities, and how entities are recreated as instances when retrieved from the datastore. The following is an example of a simple data class:

JDOはどのクラスのインスタンスが、Datastoreのエンティティであるか、またdatastoreから取り出したときにどのようにインスタンスを再作成するかを記述するため、Javaクラス(POJO)にアノテーションを使用します。

Employee.java

 import java.util.Date;
 import javax.jdo.annotations.IdGeneratorStrategy;
 import javax.jdo.annotations.IdentityType;
 import javax.jdo.annotations.PersistenceCapable;
 import javax.jdo.annotations.Persistent;
 import javax.jdo.annotations.PrimaryKey;

 @PersistenceCapable(identityType = IdentityType.APPLICATION)
 public class Employee {
 @PrimaryKey
 @Persistent(valueStrategy = IdGeneratorStrategy.IDENTITY)
 private Long id;

 @Persistent
 private String firstName;

 @Persistent
 private String lastName;

 @Persistent
 private Date hireDate;

 public Employee(String firstName, String lastName, Date hireDate) {
 this.firstName = firstName;
 this.lastName = lastName;
 this.hireDate = hireDate;
 }

 // Accessors for the fields.  JDO doesn't use these, but your application does.

 public Long getId() {
 return id;
 }

 public String getFirstName() {
 return firstName;
 }

 // ... other accessors...
 }

You interact with the datastore using a PersistenceManager object, which you obtain from a PersistenceManagerFactory object. Because setting up a PersistenceManagerFactory is expensive, you must make sure to get the instance only once in the lifetime of your application (which may span many requests). An easy way to do this is to wrap it in a singleton class, like this:

PersistenceManagerFactory オブジェクトから取得したPersistenceManagerを利用して、datastroreを操作することができます。 PersistenceManagerFactoryのセットアップは高価であるため、アプリケーションのライフタイム全体で1つのインスタンスにする必要があります。簡単な方法は次のようにシングルトンクラスでラップします。

PMF.java

 import javax.jdo.JDOHelper;
 import javax.jdo.PersistenceManagerFactory;

 public final class PMF {
 private static final PersistenceManagerFactory pmfInstance =
 JDOHelper.getPersistenceManagerFactory("transactions-optional");

 private PMF() {}

 public static PersistenceManagerFactory get() {
 return pmfInstance;
 }
 }

You can instantiate instances of data classes and store them in the datastore:

データクラスのインスタンスの作成と、それらをDatastoreに保存するには次のようにします。

 import java.util.Date;
 import javax.jdo.JDOHelper;
 import javax.jdo.PersistenceManager;
 import javax.jdo.PersistenceManagerFactory;

 import Employee;
 import PMF;

 // ...
 Employee employee = new Employee("Alfred", "Smith", new Date());

 PersistenceManager pm = PMF.get().getPersistenceManager();

 try {
 pm.makePersistent(employee);
 } finally {
 pm.close();
 }

JDO includes a query interface called JDOQL. You can use JDOQL to retrieve entities as instances of this class, as follows:

JDOはJDOQLというクエリーインターフェースを含んでいます。JDOQLを使ってエンティティを、そのクラスのインスタンスとして取得することができます。

 import java.util.List;
 import Employee;

 // ...
 String query = "select from " + Employee.class.getName() + " where lastName == 'Smith'";
 List<Employee> employees = (List<Employee>) pm.newQuery(query).execute();

Entities and Properties

A data object in the App Engine datastore is known as an entity. An entity has one or more properties, named values of one of several data types, including integers, floating point values, strings, dates, binary data, and more.

App Engine datastoreのデータオブジェクトはエンティティとして知られています。エンティティは1つ以上のプロパティをもちます。プロパティはいくつかのデータ型の一つの名前のついた値です。データ型には整数型、浮動小数型、文字列、日付、バイナリデータなどが含まれます。

Each entity also has a key that uniquely identifies the entity. The simplest key has a kind and a unique numeric ID provided by the datastore. The ID can also be a string provided by the application.

各エンティティは、エンティティ固有の一意な識別子であるキーを持ちます。もっとも単純なキーは種類とDatastoreによって提供されたユニークな数値のIDです。IDはアプリケーションによって提供される文字列であることもできます。

An application can fetch an entity from the datastore by using its key, or by performing a query that matches the entity's properties. A query can return zero or more entities, and can return the results sorted by property values. A query can also limit the number of results returned by the datastore to conserve memory and run time.

アプリケーションはキーを使うか、エンティティのプロパティとマッチするクエリーを実行することによって、Datastoreからエンティティを取得することができます。クエリーは0以上のエンティティを戻し、それらはプロパティの値によってソートすることができます。またクエリーでは、メモリと実行時間を節約するため、Datastoreから戻す結果の数を制限することもできます。

Unlike relational databases, the App Engine datastore does not require that all entities of a given kind have the same properties. The application can specify and enforce its data model using libraries included with the SDK, or its own code.

リレーショナルデータベースとは異なり、App Engine datastoreは同じ種類の全てのエンティティで同じプロパティを持つ必要がありません。アプリケーションはSDKに含まれるライブラリか独自のコードで、データモデルを識別、強制する必要があります。

A property can have one or more values. A property with multiple values can have values of mixed types. A query on a property with multiple values tests whether any of the values meets the query criteria. This makes such properties useful for testing for membership.

プロパティは1つ以上の値をとることができます。複数の値を持つプロパティは混合した型の値を持つことができます。複数の値を持つプロパティへのクエリは、それぞれの値がクエリのクライテリアにマッチするかを検査します。

Queries and Indexes

An App Engine datastore query operates on every entity of a given kind (a data class). It specifies zero or more filters on entity property values and keys, and zero or more sort orders. An entity is returned as a result for a query if the entity has at least one value (possibly null) for every property mentioned in the query's filters and sort orders, and all of the filter criteria are met by the property values.

App Engine datastoreのは与えられた種類(データクラス)の各エンティティに対してクエリを実行します。クエリは、エンティティのプロパティの値とキーに対して1つ以上のフィルタと、0以上のソート順を指定することができます。もし、クエリのフィルタとソート順で指定された各プロパティに対して、少なくとも1つの値(Nullである可能性がある)をもち、かつ全てのフィルタのクライテリアにプロパティの値が合致したとき、クエリの結果としてエンティティは返されます。

Every datastore query uses an index, a table that contains the results for the query in the desired order. An App Engine application defines its indexes in a configuration file. The development web server automatically adds suggestions to this file as it encounters queries that do not yet have indexes configured. You can tune indexes manually by editing the file before uploading the application. As the application makes changes to datastore entities, the datastore updates the indexes with the correct results. When the application executes a query, the datastore fetches the results directly from the corresponding index.

全てのdatastoreクエリは、希望の順番でクエリの結果を含むテーブルのインデックスを利用します。App Engineアプリケーションは設定ファイルでインデックスを定義します。インデックスが設定されていないクエリに遭遇すると、開発Webサーバは自動で、このファイルに提案するインデックスを追加します。アプリケーションをアップロードする前に、このファイルを編集することで、インデックスを手動でチューニングすることができます。アプリケーションがDatastoreのエンティティを変更すると、Datastoreは収集した結果によってインデックスを更新します。アプリケーションがクエリを実行したとき、データストアは対応するインデックスから直接結果を取得します。

This mechanism supports a wide range of queries and is suitable for most applications. However, it does not support some kinds of queries you may be used to from other database technologies.

このメカニズムは幅広いクエリをサポートし、ほとんどのアプリケーションに適合します。しかし、他のデータベースの技術で使用していたようないくつかの種類のクエリはサポートしていません。

Transactions and Entity Groups

With the App Engine datastore, every attempt to create, update or delete an entity happens in a transaction. A transaction ensures that every change made to the entity is saved to the datastore, or, in the case of failure, none of the changes are made. This ensures consistency of data within an entity.

App Engine datastoreでは、エンティティの作成、更新、削除をトランザクション内で試みます。トランザクションは、エンティティに行われた全ての変更をDatastoreに反映し、もし失敗した場合は、まったく反映しません。これによってエンティティのデータの一貫性を保ちます。

You can perform multiple actions on an entity within a single transaction using the transaction API. For example, say you want to increment a counter field in an object. To do so, you need to read the value of the counter, calculate the new value, then store it. Without a transaction, it is possible for another process to increment the counter between the time you read the value and the time you update the value, causing your app to overwrite the updated value. Doing the read, calculation and write in a single transaction ensures that no other process interferes with the increment.

トランザクションAPIを使うことによって、一つのトランザクション内で一つのエンティティに対して複数のアクションを行うことができます。例えば、オブジェクトのカウンタフィールドをインクリメントしたいとします。これを行うにはまず、カウンタの値を読み取り、新しい値を計算し、そしてそれを保存します。トランザクションを使わない場合、あなたが読み取ってから更新しようとする間に、他のプロセスが値を更新してしまう可能性があり、あなたのアプリケーションが更新後の値を上書きしてしまうことになります。読み取り、計算、書き込みを一つのトランザクション内で実行することにより、他のプロセスがインクリメントしないようにします。

You can make changes to multiple entities within a single transaction. To support this, App Engine needs to know in advance which entities will be updated together, so it knows to store them in a way that supports transactions. You must declare that an entity belongs to the same entity group as another entity when you create the entity. All entities fetched, created, updated or deleted in a transaction must be in the same entity group.

一つのトランザクション内で複数のエンティティを変更することもできます。これをサポートするため、App Engineはあらかじめ、どのエンティティが一緒に更新されるのかを知っておく必要があります。それらを一緒に保存することを知ることでトランザクションをサポートします。エンティティを作成したとき、他のエンティティが同じエンティティグループに所属していると宣言する必要があります。トランザクション内で全てのエンティティを、取得、作成、更新、削除するには同じエンティティグループである必要があります。

Entity groups are defined by a hierarchy of relationships between entities. To create an entity in a group, you declare that the entity is a child of another entity already in the group. The other entity is the parent. An entity created without a parent is a root entity. A root entity without any children exists in an entity group by itself. Each entity has a path of parent-child relationships from a root entity to itself (the shortest path being no parent). This path is an essential part of the entity's complete key. A complete key can be represented by the kind and ID or key name of each entity in the path.

エンティティグループは、エンティティ間のリレーションシップの階層によって定義されます。グループの中にエンティティを作成するには、そのグループ内に既に存在するほかのエンティティの子として、そのエンティティを宣言しなければなりません。その他のエンティティは親となります。親がなくて作成されたエンティティはルートエンティティとなります。一つも子供がいないルートエンティティはエンティティグループ内にそれだけで存在することができます。各エンティティは、ルートエンティティから自身の親-子関係のパスを持ちます。このパスはエンティティの完全なキーの主要部分です。完全なキーは種類と ID、またはパス内の各エンティティのキーの名前によって表すことができます。

The datastore uses optimistic concurrency to manage transactions. While one app instance is applying changes to entities in an entity group, all other attempts to update any entity in the group fail instantly. The app can try the transaction again to apply it to the updated data.

Datastore は楽観的な平行性を使ってトランザクションを管理します。一つのインスタンスが、エンティティグループ内のエンティティを変更しようとしたとき、そのグループのいずれのエンティティを更新しようとする他の全ての試みは即座に失敗します。そのアプリケーションは、更新されたデータを適用するためトランザクションを再び試みることができます。

Quotas and Limits

Each call to the datastore API counts toward the Datastore API Calls quota. Note that some library calls result in multiple calls to the underlying datastore API.

各DatastoreAPIの呼び出しは、Datastore API Callsクオータにカウントします。いくつかのライブラリ呼び出しは、Datastore APIの下層を何度もよびだすことがあるので注意してください。

Data sent to the datastore by the app counts toward the Data Sent to (Datastore) API quota. Data received by the app from the datastore counts toward the Data Received from (Datastore) API quota.

アプリケーションからデータをDatastoreへの送信は、Data Sent to(datastore) APIクオータにカウントされます。Datastoreからアプリケーションがデータを受信すると、Data Received from (Datastore) APIクオータにカウントされます。

The total amount of data currently stored in the datastore for the app cannot exceed the Stored Data (adjustable) quota. This includes entity properties and keys, but does not include indexes.

アプリケーションがDatastoreに現在保存しているデータの総量は、Stored Data (adjustable)クオータを超えることができません。これにはエンティティのプロパティとキーを含みますが、インデックスは含みません。

The amount of CPU time consumed by datastore operations applies to the following quotas:

Datastoreの操作によって消費されたCPU時間の量は次のクオータが適用されます。

  • CPU Time (adjustable)
  • Datastore CPU Time

For more information on quotas, see Quotas, and the "Quota Details" section of the Admin Console.

クオータに関する詳細は、Quotasとthe Admin Consoleの"Quota Details"を参照してください。

In addition to quotas, the following limits apply to the use of the datastore:

クオータに加えて、Datastoreの利用には次の制限が適用されます。

Limit Amount
maximum entity size 1 megabyte
maximum number of values in an index for an entity (1) 1,000 values
maximum number of entities in a batch put or batch delete 500 entities
maximum number of entities in a batch get 1,000 entities
maximum results offset for a query 1,000
  1. An entity uses one value in an index for every column × every row that refers to the entity, in all indexes. The number of indexes values for an entity can grow large if an indexed property has multiple values, requiring multiple rows with repeated values in the table.

0 件のコメント: