google appengine的数据存储API

    众所周知，google数据存储使用的是BigTable，而非传统意义上的数据库，Google AppEngine也不例外，但为了方便程序员使用，Google提供了数据存储API，来使得大家可以传统意义上的SQL来使用Google的BigTable分布式数据存储系统。

    

1. from google.appengine.ext import db
2. from google.appengine.api import users
3. #数据库模型
   
5. class Pet(db.Model):
6.   name = db.StringProperty(required=True)
7.   type = db.StringProperty(required=True, choices=set(["cat", "dog", "bird"]))
8.   birthdate = db.DateProperty()
9.   weight_in_pounds = db.IntegerProperty()
10.   spayed_or_neutered = db.BooleanProperty()
11.   owner = db.UserProperty()
12. #创建数据对象
    
14. pet = Pet(name="Fluffy",
15.           type="cat",
16.           owner=users.get_current_user())
17. pet.weight_in_pounds = 24
18. #将数据提交到数据存储系统
    
19. pet.put()

    具体的，Google准备了2套查询接口：GQL和查询对象接口，例如

1. if users.get_current_user():
2.   user_pets = db.GqlQuery("SELECT * FROM Pet WHERE pet.owner = :1",
3.                           users.get_current_user())
4.   for pet in user_pets:
5.     pet.spayed_or_neutered = True
7.   db.put(user_pets)

一 数据实体
   google AppEngine中每个数据对象被称为实体，每个实体具有几个属性。
   每个实体有一个唯一的关键词，最简单的关键词是数字ID，ID也可以是应用所指定的字符串。
   应用可以通过关键词，或根据对象的属性来提取数据。
二 模型接口
   应用通过模型来定义所需要使用的数据，模型都需要定义为db.Model类的子类。模型定义了数据实体以及对应的属性，每个属性都是Property类的子类，每个属性接受一些参数用来定义该属性是否必须赋值，或者定义默认值。例如：

1. from google.appengine.ext import db
3. class Pet(db.Model):
4.   name = db.StringProperty(required=True)
5.   type = db.StringProperty(required=True, choices=set(["cat", "dog", "bird"]))
6.   birthdate = db.DateProperty()
7.   weight_in_pounds = db.IntegerProperty()
8.   spayed_or_neutered = db.BooleanProperty()
9.   owner = db.UserProperty(required=True)

三 扩展模型接口
   基于python的动态性，google app engine提供了不同于传统数据库的功能，该功能基于expando类，使用该类可以动态设置属性，例如：

1. class Person(db.Expando):
2.   first_name = db.StringProperty()
3.   last_name = db.StringProperty()
4.   hobbies = db.StringListProperty()
6. p = Person(first_name="Albert", last_name="Johnson")
7. p.hobbies = ["chess", "travel"]
9. p.chess_elo_rating = 1350
11. p.travel_countries_visited = ["Spain", "Italy", "USA", "Brazil"]
12. p.travel_trip_count = 13

   p是Person的实例，但p可以对一些Person类中没有定义的属性进行赋值。和固定属性不同，对于未定义动态属性的实例而言，对应的属性是不存在的，而不是None(比较绕口，不知道大家明白不明白)。在查询的时候，数据存储系统很智能，只返回定义了动态属性的实例，例如：

1. p1 = Person()
2. p1.favorite = 42
3. p1.put()
5. p2 = Person()
6. p2.favorite = "blue"
7. p2.put()
9. p3 = Person()
10. p3.put()
12. people = db.GqlQuery("SELECT * FROM Person WHERE favorite < :1", 50)
13. # people has p1, but not p2 or p3
15. people = db.GqlQuery("SELECT * FROM Person WHERE favorite > :1", 50)
16. # people has no results

四 属性与类型
   字符串、长字符串、二进制数据
   appengine支持Unicode字符串，因此不需要为中文问题而担忧。

1. class MyModel(db.Model):
2.   string = db.StringProperty()
4. obj = MyModel()
6. # Python Unicode literal syntax fully describes characters in a text string.
7. obj.string = u"kittens"
9. # unicode() converts a byte string to a Unicode value using the named codec.
10. obj.string = unicode("kittens", "latin-1")
12. # A byte string is assumed to be text encoded as ASCII (the 'ascii' codec).
13. obj.string = "kittens"
15. # Short string properties can be used in query filters.
16. results = db.GqlQuery("SELECT * FROM MyModel WHERE string = :1", u"kittens")

   长字符串例子：

1. class MyModel(db.Model):
2.   text = db.TextProperty()
4. obj = MyModel()
6. # Text() can take a Unicode value.
7. obj.text = db.Text(u"lots of kittens")
9. # Text() can take a byte string and the name of an encoding.
10. obj.text = db.Text("lots of kittens", "latin-1")
12. # If no encoding is specified, a byte string is assumed to be ASCII text.
13. obj.text = db.Text("lots of kittens")
15. # Text properties can store large values.
16. obj.text = db.Text(open("a_tale_of_two_cities.txt").read(), "utf-8")

   二进制数据例子：

1. class MyModel(db.Model):
2.   blob = db.BlobProperty()
4. obj = MyModel()
6. obj.blob = db.Blob(open("image.png").read())

   注意：长字符串和二进制数据是不被索引的，因此对该字段的查询是不会成功的。
   列表：

1. class MyModel(db.Model):
2.   numbers = db.ListProperty(long)
4. obj = MyModel()
5. obj.numbers = [2, 4, 6, 8, 10]
7. obj.numbers = ["hello"]  # ERROR: MyModel.numbers must be a list of longs.
9. # Get all entities where numbers contains a 6.
10. results = db.GqlQuery("SELECT * FROM MyModel WHERE numbers = 6")
12. # Get all entities where numbers contains at least one element less than 10.
13. results = db.GqlQuery("SELECT * FROM MyModel WHERE numbers < 10")

   引用(类似于表间关联)：

1. class FirstModel(db.Model):
2.   prop = db.IntegerProperty()
4. class SecondModel(db.Model):
5.   reference = db.ReferenceProperty(FirstModel)
7. obj1 = FirstModel()
8. obj1.prop = 42
9. obj1.put()
11. obj2 = SecondModel()
13. # A reference value is the key of another entity.
14. obj2.reference = obj1.key()
16. # Assigning a model instance to a property uses the entity's key as the value.
17. obj2.reference = obj1
18. obj2.put()

   注意：长字符串、二进制数据不会被索引   
   
五 创建、更新记录(想了半天，还是觉得用记录还描述比较贴切，实体...太奇怪了)
  

1. pet = Pet(name="Fluffy",
2.           type="cat",
3.           owner=users.get_current_user())
5. pet.put()
7. db.put(pet)
9. if users.get_current_user():
10.   user_pets = db.GqlQuery("SELECT * FROM Pet WHERE pet.owner = :1",
11.                           users.get_current_user())
12.   for pet in user_pets:
13.     pet.spayed_or_neutered = True
15.   db.put(user_pets)

   还是很容易了，直接将对应的记录做一个put操作就可以创建、或者更新记录了。
六 查询记录集
   对象查询：

1. class Story(db.Model):
2.   title = db.StringProperty()
3.   date = db.DateTimeProperty()
5. query = Story.all()
7. query.filter('title =', 'Foo')
8. query.order('-date')
9. query.ancestor(key)#这句没明白做什么的？先留着吧。
11. # These methods can be chained together on one line.
12. query.filter('title =', 'Foo').order('-date').ancestor(key)

   GQL查询：

1. # Parameters can be bound with positional arguments.
2. query = db.GqlQuery("SELECT * FROM Story WHERE title = :1 "
3.                     "AND ANCESTOR IS :2 "
4.                     "ORDER BY date DESC",
5.                     'Foo', key)
7. # Or, parameters can be bound with keyword arguments.
8. query = db.GqlQuery("SELECT * FROM Story WHERE title = :title "
9.                     "AND ANCESTOR IS :parent "
10.                     "ORDER BY date DESC",
11.                     title='Foo', parent=key)
13. # String, number and Boolean values can be literal values in the string.
14. query = db.GqlQuery("SELECT * FROM Story WHERE title = 'Foo' "
15.                     "AND ANCESTOR IS :parent "
16.                     "ORDER BY date DESC",
17.                     parent=key)

18. query = Story.gql("WHERE title = :title "
                      "AND ANCESTOR IS :parent "
                      "ORDER BY date DESC",
                      title='Foo', parent=key)

七 获取数据

1. results = query.fetch(10)
2. for result in results:
3.   print "Title: " + result.title

   说真的，这个方式获取数据，比使用Python的DB API还简单呢，不过还有其他方式。

1. for result in query:
2.   print "Title: " + result.title

   可以很容易地发现，对query直接进行遍历可以不需要设定查询数据的条数。
   注意：Google AppEngine中每个查询最多返回1000条数据，不管limit和offset设置的值为多少。例如，对于大于1000条的数据，如果offset设置为100，那么实际返回900条数据。我想知道的是，如果有1万条数据，那么每次返回100条，不知道是否可以将1万条数据全部遍历，如果不可以的话，那么岂不是非常不妙啊？
   要获取一条数据也很简单，如下：

1. entity.put()
2. key = entity.key()
4. # ...
6. entity = db.get(key)
8. pets = GqlQuery("SELECT * FROM Pet WHERE name = :1", "Fluffy")
9. pet = pets.get()
11. owner_name = pet.owner.name
12. #在模板中如下使用
13. obj = MyModel(name="Foo")
14. self.response.write('<a href="/view?key=%s">%s</a>' % (str(obj.key()), 
15.                                                       obj.name()))
17. # ...
18. #在页面中如下使用
19. key_name = self.request.get('key')
20. obj = db.get(db.Key(key_name))

八 删除数据

1. q = db.GqlQuery("SELECT * FROM Message WHERE create_date < :1", earliest_date)
2. results = q.fetch(10)
3. for result in results:
4.   result.delete()
5. 
   
6. # or...
7. 
   
8. q = db.GqlQuery("SELECT * FROM Message WHERE create_date < :1", earliest_date)
9. results = q.fetch(10)
10. db.delete(results)

九 ID Or Key_name
   如果没有设置ID的话，可以使用obj.key()获得某条记录的ID
   可以使用db.Key(ID)或者Entity.Key(ID)获取obj。

十 索引的配置 Index.yaml 例子：

1. indexes:
3. - kind: Cat
4.   ancestor: no
5.   properties:
6.   - name: name
7.   - name: age
8.     direction: desc
10. - kind: Cat
11.   properties:
12.   - name: name
13.     direction: asc
14.   - name: whiskers
15.     direction: desc
17. - kind: Store
18.   ancestor: yes
19.   properties:
20.   - name: business
21.     direction: asc
22.   - name: owner
23.     direction: asc

   ancestor如果有源查询或者Query，为True，默认为False
   注意：实际上，如果你没有对该文件进行配置，google appengine会对它进行默认的配置，当然是为了优化查询了。

附录：
一 Model Class:(文档:http://code.google.com/intl/zh-CN/appengine/docs/datastore/modelclass.html)
类方法：

• Model.get()
• Model.get_by_id()
• Model.get_by_key_name()
• Model.get_or_insert()
• Model.all()
• Model.gql()
• Model.kind()
• Model.properties()

实例方法：

• key()
• put()
• delete()
• is_saved()
• parent()
• parent_key()
• to_xml()

二 Query类
实例方法：

• filter()
• order()
• ancestor()
• get()
• fetch()
• count()

三 支持的属性——属性类型

Property class Value type Sort order StringProperty str
unicode Unicode (str is treated as ASCII) BooleanProperty bool False < True IntegerProperty int
long
Numeric FloatProperty float Numeric DateTimeProperty
DateProperty
TimeProperty
datetime.datetime Chronological ListProperty
StringListProperty list of a supported type If ascending, by least element; if descending, by greatest element ReferenceProperty
SelfReferenceProperty db.Key By path elements (kind, ID or name, kind, ID or name...) UserProperty users.User By email address (Unicode) BlobProperty db.Blob (not orderable) TextProperty db.Text (not orderable) CategoryProperty db.Category Unicode LinkProperty db.Link Unicode EmailProperty db.Email Unicode GeoPtProperty db.GeoPt By latitude, then longitude IMProperty db.IM Unicode PhoneNumberProperty db.PhoneNumber Unicode PostalAddressProperty db.PostalAddress Unicode RatingProperty db.Rating Numeric四 异常

exception Error()

exception BadArgumentError()

exception BadFilterError()

exception BadKeyError()

exception BadPropertyError()

exception BadQueryError()

exception BadRequestError()

exception BadValueError()

exception ConfigurationError()

exception DuplicatePropertyError()

exception InternalError()

exception KindError()

exception NotSavedError()

exception PropertyError()

exception ReservedWordError()

exception Rollback()

exception Timeout()

exception TransactionFailedError()

exception CapabilityDisabledError()

五 事务处理
http://code.google.com/intl/zh-CN/appengine/docs/datastore/transactions.html