Observação: o Python 2.7 chegou ao fim do suporte em 31 de janeiro de 2024. Os aplicativos Python 2.7 atuais continuarão a ser executados e a receber tráfego. No entanto, o App Engine pode bloquear a reimplantação de aplicativos que usam ambientes de execução após o término da data de suporte. Recomendamos que você migre para a versão compatível mais recente do Python.

Funções do Datastore

Observação: é altamente recomendável a desenvolvedores que criam novos aplicativos usar a biblioteca de cliente NDB, porque ela oferece diversos benefícios em comparação com esta biblioteca de cliente, como armazenamento em cache automático de entidades por meio da API Memcache. Se você estiver usando a antiga biblioteca de cliente DB, leia o Guia de migração de DB para NDB.

As funções descritas nesta página são definidas no pacote google.appengine.ext.db.

Funções

allocate_ids (model, count)

Aloca um lote de IDs no Datastore para um tipo de Datastore e uma combinação pai.

Os IDs alocados nessa maneira não serão usados pelo gerador de sequência de ID automático do Datastore, mas podem ser usados em chaves de entidade sem conflito.

Argumentos

model: Chave de modelo referente à alocação de um lote de IDs. Trata-se de uma chave regular, mas somente o pai e o tipo da chave são necessários para determinar qual sequência de IDs usar.
count: Número de IDs a alocar.

Retorna uma tupla do primeiro e do último código alocados. Por exemplo, se alocasse dez códigos usando essa função, você receberia um retorno no formato (1, 10), e não uma lista completa de códigos criados.

Exemplo de alocação e uso de códigos:

# allocate for MyModel without an instance
handmade_key = db.Key.from_path('MyModel', 1)
first_batch = db.allocate_ids(handmade_key, 10)
first_range = range(first_batch[0], first_batch[1] + 1)

# or allocate using an existing key
model_instance = MyModel.all().get()
second_batch = db.allocate_ids(model_instance.key(), 10)
second_range = range(second_batch[0], second_batch[1] + 1)

# and then use them! woo!
my_id = second_range.pop(0)
new_key = db.Key.from_path('MyModel', my_id)
new_instance = MyModel(key=new_key)
new_instance.put()
assert new_instance.key().id() == my_id

# the Datastore will not assign ids in first_batch or second_batch
another_instance = MyModel()
another_instance.put()
assert another_instance.key().id() not in first_range
assert another_instance.key().id() not in second_range

allocate_ids_async (model, count)

Aloca de maneira assíncrona um lote de códigos no Datastore para um tipo de Datastore e uma combinação pai.

Essa função é idêntica a allocate_ids(), exceto pelo fato de retornar um objeto assíncrono. É possível chamar get_result() no valor de retorno para bloquear na chamada e retornar o resultado.

Argumentos

model: Uma instância db.Model, chave, ou string para servir como um modelo especificando a sequência de ID na qual alocar os IDs. Os IDs retornados são usados somente em entidades com o mesmo pai (se houver) e o tipo dessa chave.
count: Número de IDs a alocar.

Retorna uma tupla do primeiro e do último código alocados. Por exemplo, se tivesse alocado dez códigos que usam essa função, você receberia um valor de retorno no formato (1, 10), e não uma lista completa de códigos criados.

allocate_id_range (model, start, end, **kwargs)

Aloca um intervalo de códigos com pontos de extremidade específicos. Depois que esses códigos tiverem sido alocados, você poderá atribuí-los manualmente a entidades recém criadas.

O alocador de códigos automáticos do Datastore nunca atribui uma chave já alocada, seja por meio da alocação de códigos automáticos ou de uma chamada "allocate_ids" explícita. Dessa forma, as entidades gravadas nesse intervalo de chaves jamais serão substituídas. Entretanto, gravar entidades com chaves atribuídas manualmente nesse intervalo pode substituir entidades existentes ou novas entidades gravadas por uma solicitação separada, dependendo do estado de intervalo de chaves retornado.

Só use essa função caso você tenha um intervalo de IDs numérico atual que queira reservar. Por exemplo, carregar entidades em massa que já tenham IDs. Se você não se importar com os IDs recebidos, use allocate_ids().

Argumentos

model: Uma instância db.Model, chave, ou string para servir como um modelo especificando a sequência de ID na qual alocar os IDs. Os IDs retornados são usados somente em entidades com o mesmo pai (se houver) e o tipo dessa chave.
start
end: O último ID a ser alocado, um número.

Retorna um de (KEY_RANGE_EMPTY, KEY_RANGE_CONTENTION, KEY_RANGE_COLLISION). Se não KEY_RANGE_EMPTY, isso representa um possível problema com o uso do intervalo de chaves alocado.

create_transaction_options (**kwargs)

Cria um objeto de opções de transação (classe TransactionOptions) para controlar a execução da transação. Você passa o objeto resultante como o primeiro argumento para a função run_in_transaction_options().

Argumentos

propagation

O que fazer se essa função transacional for chamada dentro de outra transação:

ALLOWED: Continua usando uma transação se já estiver em uma. Do contrário, inicia uma.
Observação: caso uma função que use essa política gere uma exceção, talvez não seja seguro detectar essa exceção e confirmar a transação externa. A função talvez tenha deixado essa transação externa em mau estado.
MANDATORY: Continua na transação atual, se houver. Caso contrário, gera uma exceção BadRequestError.
Observação: caso uma função que use essa política gere uma exceção, talvez não seja seguro detectar essa exceção e confirmar a transação externa. A função talvez tenha deixado essa transação externa em mau estado.
INDEPENDENT: Cria uma nova transação, pausando todas as atuais.
Observação: uma função que usa essa política não precisa retornar entidades lidas na nova transação, porque as entidades não são consistentes de maneira transacional com a transação externa.
NESTED: (Ainda não compatível) cria uma transação aninhada dentro de uma atual.

xg

Se True, permitir transações entre grupos (XG). Gera uma exceção BadArgumentError se definido como um valor não booleano.

retries

Número de novas tentativas em caso de falha na confirmação da transação.

deadline

Tempo máximo de espera, em segundos, para que o Datastore retorne um resultado antes de cancelar com um erro. Aceita um número inteiro ou um valor de ponto flutuante. Não é aumentado além do valor padrão de 60 segundos, mas diminuído para garantir que uma determinada operação falhe rapidamente. Por exemplo, para retornar uma resposta mais rápida ao usuário, repita a operação, tente uma operação diferente ou adicione essa operação a uma fila de tarefas.

O exemplo a seguir cria as opções para uma transação XG subsequente:

from google.appengine.ext import db

xg_on = db.create_transaction_options(xg=True)

def my_txn():
  x = MyModel(a=3)
  x.put()
  y = MyModel(a=7)
  y.put()

db.run_in_transaction_options(xg_on, my_txn)

delete (models, deadline=60)

Exclui uma ou mais instâncias de modelo do Datastore.

Argumentos

models: Uma instância de modelo, uma chave de entidade ou uma lista (ou outro iterável) de instâncias de modelo ou chaves de entidade a serem excluídas.
deadline: Tempo máximo de espera, em segundos, para que o Datastore retorne um resultado antes de cancelar com um erro. Aceita um número inteiro ou um valor de ponto flutuante. Não é aumentado além do valor padrão de 60 segundos, mas diminuído para garantir que uma determinada operação falhe rapidamente. Por exemplo, se quiser retornar uma resposta mais rápida ao usuário, repita a operação, tente uma diferente ou adicione essa operação a uma fila de tarefas.

Assim como em put(), se várias chaves forem fornecidas, elas poderão estar em mais de um grupo de entidades.

Uma exceção será gerada se ocorrer um erro durante a operação, mesmo se algumas das entidades tiverem sido excluídas. Se a chamada retornar sem gerar uma exceção, todas as entidades terão sido excluídas.

Cuidado: excluir várias entidades em uma única operação não garante que as exclusões aconteçam atomicamente, a menos que a operação seja realizada em uma transação. Outros processos que consultam o Datastore podem ver resultados inconsistentes mesmo quando a consulta é realizada com consistência forte.

delete_async (models, deadline=60)

Exclui de maneira assíncrona uma ou mais instâncias de modelo do Datastore.

Essa função é idêntica a delete(), exceto pelo fato de retornar um objeto assíncrono. É possível chamar get_result() no valor de retorno para bloquear a chamada.

Argumentos

models: Uma instância de modelo, uma chave de entidade ou uma lista (ou outro iterável) de instâncias de modelo ou chaves de entidade a serem excluídas.
deadline: Tempo máximo de espera, em segundos, para que o Datastore retorne um resultado antes de cancelar com um erro. Aceita um número inteiro ou um valor de ponto flutuante. Não é aumentado além do valor padrão de 60 segundos, mas diminuído para garantir que uma determinada operação falhe rapidamente. Por exemplo, se quiser retornar uma resposta mais rápida ao usuário, repita a operação, tente uma diferente ou adicione essa operação a uma fila de tarefas.

Assim como em put(), se várias chaves forem fornecidas, elas poderão estar em mais de um grupo de entidades.

Essa função retorna um objeto que permite bloquear o resultado da chamada.

get (keys, read_policy=STRONG_CONSISTENCY, deadline=60)

Busque as instâncias de Model específicas com a(s) chave(s) fornecida(s) pelo Datastore.

Argumentos

keys

A chave da entidade a ser recuperada, uma representação de string da chave, uma lista de chaves ou as representações de string correspondentes.

read_policy

Política de leitura que especifica o nível desejado de consistência de dados:

STRONG_CONSISTENCY: Garante os resultados mais recentes, mas limitados a um único grupo de entidades.
EVENTUAL_CONSISTENCY: Abrange diversos grupos de entidades, mas de vez em quando retorna resultados obsoletos. Em geral, as consultas de consistência eventual são executadas mais rapidamente do que as de consistência forte, mas não há garantias.

Observação: consultas globais (não ancestrais) ignoram esse argumento.

deadline

Tempo máximo de espera, em segundos, para que o Datastore retorne um resultado antes de cancelar com um erro. Aceita um número inteiro ou um valor de ponto flutuante. Não é aumentado além do valor padrão de 60 segundos, mas diminuído para garantir que uma determinada operação falhe rapidamente. Por exemplo, se quiser retornar uma resposta mais rápida ao usuário, repita a operação, tente uma diferente ou adicione essa operação a uma fila de tarefas.

Se keys consistir em uma única chave (ou na representação de string), essa função retornará a instância de modelo associada à chave se ela existir no Datastore. Caso contrário, None. Quando keys é uma lista, o valor de retorno é uma lista correspondente de instâncias do modelo com valores None onde não houver entidades para uma determinada chave.

Consulte também Model.get().

get_async (keys, read_policy=STRONG_CONSISTENCY, deadline=60)

Busca de maneira assíncrona a(s) instância(s) de Modelo especificada(s) no Datastore.

Essa função é idêntica a get(), exceto pelo fato de retornar um objeto assíncrono. É possível chamar get_result() no valor de retorno a ser bloqueado na chamada e retornar o resultado.

Argumentos

keys

A chave da entidade a ser recuperada, uma representação de string da chave, uma lista de chaves ou as representações de string correspondentes.

read_policy

Política de leitura que especifica o nível desejado de consistência de dados:

STRONG_CONSISTENCY: Garante os resultados mais recentes, mas limitados a um único grupo de entidades.
EVENTUAL_CONSISTENCY: Abrange diversos grupos de entidades, mas de vez em quando retorna resultados obsoletos. Em geral, as consultas de consistência eventual são executadas mais rapidamente do que as de consistência forte, mas não há garantias.

Observação: consultas globais (não ancestrais) ignoram esse argumento.

deadline

Tempo máximo de espera, em segundos, para que o Datastore retorne um resultado antes de cancelar com um erro. Aceita um número inteiro ou um valor de ponto flutuante. Não é aumentado além do valor padrão de 60 segundos, mas diminuído para garantir que uma determinada operação falhe rapidamente. Por exemplo, se quiser retornar uma resposta mais rápida ao usuário, repita a operação, tente uma diferente ou adicione essa operação a uma fila de tarefas.

Consulte também Model.get().

get_indexes ()

Retorna uma lista de índices compostos pertencentes ao aplicativo de chamada.

O exemplo a seguir ilustra como receber e usar os índices:

def get_index_state_as_string(index_state):
  return {db.Index.BUILDING:'BUILDING', db.Index.SERVING:'SERVING',
          db.Index.DELETING:'DELETING', db.Index.ERROR:'ERROR'}[index_state]

def get_sort_direction_as_string(sort_direction):
  return {db.Index.ASCENDING:'ASCENDING',
          db.Index.DESCENDING:'DESCENDING'}[sort_direction]


def dump_indexes():
  for index, state in db.get_indexes():
    print "Kind: %s" % index.kind()
    print "State: %s" % get_index_state_as_string(state)
    print "Is ancestor: %s" % index.has_ancestor()
    for property_name, sort_direction in index.properties():
      print "  %s:%s" % (property_name,
                         get_sort_direction_as_string(sort_direction))

get_indexes_async ()

Retorna de maneira assíncrona uma lista de índices compostos pertencentes ao aplicativo de chamada.

is_in_transaction ()

Mostra um booleano indicando se o escopo atual está em execução em uma transação.

model_to_protobuf (model_instance)

Cria a serialização do buffer de protocolo de uma instância de Model. Um buffer de protocolo é o formato de serialização do Google usado em chamadas de procedimento remoto e pode ser útil para serializar objetos do Datastore para fins de backup e restauração.

Cuidado: para buffers de protocolo, essa função usa um formato diferente (anterior) do formato de buffer do protocolo de código aberto, e não é compatível com a implementação de código aberto.

Argumento

model_instance: A instância da classe Model (ou uma subclasse) a ser serializada.

Retorna a serialização do buffer de protocolo do objeto, como uma string de byte.

model_from_protobuf (pb)

Cria uma Model instância com base em uma serialização de buffer de protocolo. Veja model_to_protobuf() para mais informações.

Argumento

pb: model_to_protobuf().

Retorna um objeto da classe de tipo apropriada. Se a classe de tipo não existir, será gerada uma exceção KindError. Se o objeto não for válido de acordo com o modelo, uma exceção BadValueError será gerada.

Salve o novo objeto no Datastore como qualquer outra instância de Model, por exemplo, ao chamar o método put(). O objeto mantém a chave que tinha quando o buffer de protocolo foi criado. Se um objeto com essa chave já existir no Datastore, salvar o objeto desserializado substituirá o objeto existente.

Cuidado: se a chave do objeto usar um código atribuído pelo sistema e esse código ainda não tiver sido alocado para o caminho e o tipo fornecidos, a gravação será bem-sucedida, mas o código não será reservado. Um objeto criado no futuro pode receber esse código, e ele substituiria o objeto anterior. Para fins de segurança, restaure objetos apenas no mesmo aplicativo em que eles existiam quando foram serializados.

model_is_projection (model_instance)

Retorna True se a consulta especificada (model_instance) for uma consulta de projeção em vez de uma consulta para uma entidade completa.

Argumento

model_instance: A consulta que você está verificando para determinar se é uma consulta de projeção.

Retorna True se a consulta é uma consulta de projeção, False se não for.

put (models, deadline=60)

Grava uma ou mais instâncias de modelo no Datastore.

Argumentos

models: Uma instância ou uma lista de instâncias de modelo a serem armazenados.
deadline: Tempo máximo de espera, em segundos, para que o Datastore retorne um resultado antes de cancelar com um erro. Aceita um número inteiro ou um valor de ponto flutuante. Não é aumentado além do valor padrão de 60 segundos, mas diminuído para garantir que uma determinada operação falhe rapidamente. Por exemplo, para retornar uma resposta mais rápida ao usuário, repita a operação, tente uma operação diferente ou adicione essa operação a uma fila de tarefas.

Se forem fornecidas várias instâncias de modelo, elas poderão estar em mais de um grupo de entidades.

Uma exceção será sempre gerada se qualquer erro ocorrer durante a operação, mesmo se alguma das entidades tiver sido realmente gravada. Se a chamada retornar sem gerar uma exceção, todas as entidades foram gravadas com êxito.

Se models consistir em uma única instância de modelo, essa função retornará o objeto Key correspondente. Se models for uma lista, o valor de retorno será uma lista dos objetos Key correspondentes.

Cuidado: gravar várias entidades em uma única operação não garante que as gravações aconteçam atomicamente, a menos que a operação seja realizada dentro de uma transação. Outros processos que consultam o Datastore podem ver resultados inconsistentes mesmo quando a consulta é realizada com consistência forte.

put_async (models, deadline=60)

Grava uma ou mais instâncias de modelo no Datastore.

Essa função é idêntica a put(), exceto pelo fato de retornar um objeto assíncrono. É possível chamar get_result() no valor de retorno a ser bloqueado na chamada e retornar o resultado.

Argumentos

models: Uma instância ou uma lista de instâncias de modelo a serem armazenados.
deadline: Tempo máximo de espera, em segundos, para que o Datastore retorne um resultado antes de cancelar com um erro. Aceita um número inteiro ou um valor de ponto flutuante. Não é aumentado além do valor padrão de 60 segundos, mas diminuído para garantir que uma determinada operação falhe rapidamente. Por exemplo, para retornar uma resposta mais rápida ao usuário, repita a operação, tente uma operação diferente ou adicione essa operação a uma fila de tarefas.

Se forem fornecidas várias instâncias de modelo, elas poderão estar em mais de um grupo de entidades.

Essa função retorna um objeto assíncrono no qual get_result() pode ser chamado. Os resultados retornados são os mesmos que em put().

query_descendants (model_instance)

Retorna uma consulta para todos os descendentes de uma instância de modelo.

Argumento

model_instance: A instância de modelo com os descendentes que você quer encontrar.

run_in_transaction (function, *args, **kwargs)

Executa uma função que contém atualizações do Datastore em uma única transação. Se algum código gerar uma exceção durante a transação, todas as atualizações feitas na transação serão revertidas. Como alternativa, é possível usar o decorador @db.transactional().

Argumentos

function: Função a ser executada.
args: Argumentos de posição a serem transmitidos para a função.
kwargs: Argumentos de palavra-chave a serem transmitidos para a função.

Se a função retornar um valor, run_in_transaction() retornará o valor ao autor da chamada.

Se a função gerar uma exceção, a transação será revertida. Se for uma exceção Rollback, ela não será gerada novamente. Qualquer outra exceção será gerada novamente para o autor da chamada.

O Datastore usa bloqueio otimista e é recuperado para transações. Se a transação preparada pela função não puder ser confirmada, run_in_transaction() chamará a função novamente, repetindo a transação até três vezes. Para usar um número diferente de tentativas, use run_in_transaction_custom_retries(). Como a função de transação pode ser chamada mais de uma vez para uma única transação, a função não pode ter efeitos secundários, incluindo modificações em argumentos.

Se não for possível confirmar a transação, por exemplo, por causa de uma alta taxa de contenção, uma exceção TransactionFailedError será gerada.

from google.appengine.ext import db

class Counter(db.Model):
  name = db.StringProperty()
  count = db.IntegerProperty(default=0)

def decrement(key, amount=1):
  counter = db.get(key)
  counter.count -= amount
  if counter.count < 0:        # Don't let counter go negative
    raise db.Rollback()
  db.put(counter)

q = db.GqlQuery("SELECT * FROM Counter WHERE name = :1", "foo")
counter = q.get()
db.run_in_transaction(decrement, counter.key(), amount=5)

run_in_transaction_custom_retries (retries, function, *args, **kwargs)

Executa uma função que contém atualizações do Datastore em uma única transação, repetindo a transação um número especificado de vezes em caso de contenção. Se algum código gerar uma exceção durante a transação, todas as atualizações feitas na transação serão revertidas.

Além da capacidade de especificar o número de tentativas, esta função se comporta de maneira idêntica a run_in_transaction().

Argumentos

retries: Número máximo de vezes para chamar a função em caso de contenção no grupo de entidades (mais de um usuário tentando modificar o grupo de maneira simultânea).
function: Função a ser executada.
args: Argumentos de posição a serem transmitidos para a função.
kwargs: Argumentos de palavra-chave a serem transmitidos para a função.

run_in_transaction_options (options, function, *args, **kwargs)

Executa uma função que contém atualizações do Datastore em uma única transação que usa as opções especificadas em um objeto de opções de transação. Se qualquer código gerar uma exceção durante a transação, todas as atualizações do Datastore feitas na transação serão revertidas.

Para transações entre grupos (XG), o parâmetro xg no objeto de opções de transação precisa ser definido como True.

Argumentos

options: O objeto de opções da transação que contém as configurações usadas por essa transação. Para ativar transações XG, o parâmetro xg precisa ser definido como True.
function: Função a ser executada.
args: Argumentos de posição a serem transmitidos para a função.
kwargs: Argumentos de palavra-chave a serem transmitidos para a função.

Se a função retornar um valor, run_in_transaction_options() retornará o valor ao autor da chamada.

O Datastore usa bloqueio otimista e é recuperado para transações. Se a transação preparada pela função não puder ser consolidada, run_in_transaction_options() chama a função novamente, repetindo a transação até o número de novas tentativas especificado no objeto de opções de transação. Como a função de transação pode ser chamada mais de uma vez para uma única transação, a função não precisa ter efeitos colaterais, inclusive modificações em argumentos.

Se não for possível confirmar a transação, por exemplo, por causa de uma alta taxa de contenção, uma exceção TransactionFailedError será gerada.

Veja no seguinte exemplo como usar essa função para executar uma transação entre grupos:

from google.appengine.ext import db

xg_options = db.create_transaction_options(xg=True)

def my_txn():
  x = MyModel(a=3)
  x.put()
  y = MyModel(a=7)
  y.put()

db.run_in_transaction_options(xg_options, my_txn)

to_dict (model_instance, dictionary=None)

Cria e retorna uma representação de dicionário de uma instância de modelo.

Argumentos

model_instance: Instância de modelo a ser copiada.
dictionary: Se presente, dicionário em que os dados do modelo são mesclados. Os valores de modelo substituem valores no dicionário. As entradas de dicionário não correspondentes aos campos na instância de modelo são preservadas.

Decoradores

@db.transactional (propagation=ALLOWED, xg=False, retries=3, deadline=60)

Faz com que uma função seja executada dentro de uma transação db. Assim, em vez de chamar run_in_transaction(func), você chama func().

Argumentos

propagation

O que fazer se essa função transacional for chamada dentro de outra transação:

ALLOWED: Continua usando uma transação se já estiver em uma. Do contrário, inicia uma.
Observação: caso uma função que use essa política gere uma exceção, talvez não seja seguro detectar essa exceção e confirmar a transação externa. A função talvez tenha deixado essa transação externa em mau estado.
MANDATORY: Continua na transação atual, se houver. Caso contrário, gera uma exceção BadRequestError.
Observação: caso uma função que use essa política gere uma exceção, talvez não seja seguro detectar essa exceção e confirmar a transação externa. A função talvez tenha deixado essa transação externa em mau estado.
INDEPENDENT: Cria uma nova transação, pausando todas as atuais.
Observação: uma função que usa essa política não precisa retornar entidades lidas na nova transação, porque as entidades não são consistentes de maneira transacional com a transação externa.
NESTED: (Ainda não compatível) cria uma transação aninhada dentro de uma atual.

xg

Se True, permitir transações entre grupos (XG). Gera uma exceção BadArgumentError se definido como um valor não booleano.

retries

Número de novas tentativas em caso de falha na confirmação da transação.

deadline

Tempo máximo de espera, em segundos, para que o Datastore retorne um resultado antes de cancelar com um erro. Aceita um número inteiro ou um valor de ponto flutuante. Não é aumentado além do valor padrão de 60 segundos, mas diminuído para garantir que uma determinada operação falhe rapidamente. Por exemplo, se quiser retornar uma resposta mais rápida ao usuário, repita a operação, tente uma diferente ou adicione essa operação a uma fila de tarefas.

@db.non_transactional (allow_existing=True)

Garante que uma função seja executada fora de uma transação db, mesmo que seja chamada de dentro de uma transação.

Argumento

allow_existing: Se True, permitir que a função seja chamada dentro de uma transação atual. Se False, lançar uma exceção BadRequestError.