English ▼
Skip to page content Skip to main navigation
e.g. "templates" or "datastore"

# Prospective Search Functions (Python)

#### Experimental!

Prospective Search is an experimental, innovative, and rapidly changing new feature for App Engine. Unfortunately, being on the bleeding edge means that we may make backwards-incompatible changes to Prospective Search. We will inform the community when this feature is no longer experimental.

The `google.appengine.api.prospective_search` package provides the following functions:

get_document(request)

  Decodes the document from a prospective search result `POST` request. Returns `document`, which is the `db.Model` document from the match() call.

  Arguments:

  request
    `POST` request object received as a result of a match operation. Request is defined in `google.appengine.ext.webapp`.
get_subscription(document_class, sub_id, topic=None)

  Returns a tuple which contains the subscription ID, query, expiration time, and the state of a single subscription.

  - `sub_id` is the subscription ID.
  - `query` is the query associated with the subscription.
  - `expiration_time` is the number of seconds since the epoch when the subscription expires.
  - `state` is one of:
    - SubscriptionState.OK – Subscription is active.
    - SubscriptionState.PENDING – Successfully registered but not yet active.
    - SubscriptionState.ERROR – Inactive due to an error. (See the error value for explanation.)

  Arguments:

  document_class
    `document_class` is a `db.Model` class name.
  sub_id
    Subscription ID to be retrieved.
  topic
    The topic name explicitly specified in the `subscribe()` call, or the `db.Model` class name.
list_subscriptions(document_class, sub_id_start='', topic=None, max_results=1000, expires_before=None)

  Returns a list of tuples. Each tuple contains the subscription ID, query, expiration time, and the state of the subscription.

  - `sub_id` is the subscription ID.
  - `query` is the query associated with the subscription.
  - `expiration_time` is the number of seconds since the epoch when the subscription expires.
  - `state` is one of:
    - SubscriptionState.OK – Subscription is active.
    - SubscriptionState.PENDING – Successfully registered but not yet active.
    - SubscriptionState.ERROR – Inactive due to an error (see error value for explanation).

  Arguments:

  document_class
    A class derived from `db.Model`.
  sub_id_start
    Limits the returned subscriptions to those that are lexicographically equal to or greater than the specified value.
  topic
    The topic name explicitly specified in the `subscribe()` call or the `db.Model` class name.
  max_results
    Sets the maximum number of subscriptions to return.
  expires_before
    Limits the returned subscriptions to those that expire before the specified time.
list_topics(max_results=1000,topic_start=None)

  Returns a list of topics as strings.

  Arguments:

  max_results
    Specifies the maximum number of topics to return.
  topic_start
    Limits the returned topics to those whose names are lexicographically equal to or greater than the specified value.
match(document, topic=None, result_key=None, result_relative_url='/_ah/prospective_search', result_task_queue='default', result_batch_size=100, result_return_document=True)

  Matches a document with all subscribed queries on a specific `topic` and returns the results and `db.Model` document on the Task Queue. Results are subject to the Task Queue Quotas and Limits.

  Arguments:

  document
    An instance of a `db.Model` document.
  topic
    The topic derived from the name of the `db.Model` document. Only subscriptions to this topic are matched against this document.
  result_key
    Key to return if document is matched. A `result_key` can be used to identify document that is too large for the Task Queue to return. See Using Prospective Search.
  result_relative_url
    URL of the Task Queue event handler for results.
  result_task_queue
    Name of the Task Queue in which to put batched results.
  result_batch_size
    Number of subscriptions IDs per task queue task batch.
  result_return_document
    If True, this returns documents with match results as long as the document fits within the Task Queue task size limits.
subscribe(document_class, vanilla_query, sub_id, topic=None, lease_duration_sec=0)

  Register subscriptions using a subscription ID and a query. Expect a delay of a few seconds between when `subscribe()` returns successfully and when the subscription becomes registered and active. If a subscription with the same ID already exists, it is overwritten.

  Arguments:

  document_class
    `document_class` is a `db.Model` class name.
  vanilla_query
    `vanilla_query` is a string or unicode query for documents of the type specified by `document_class`.
  sub_id
    `sub_id` is a unique string identifier for the subscription and is returned when the subscription is matched. `subscribe()` overwrites subscriptions with the same `sub_id` The size of the `sub_id` contributes to the size of the results, which are subject to the usual Task Queue Quotas and Limits.
  topic
    `topic` specifies the namespace for the subscriptions to match. In `db.Model`, topics are set to the document's class name by default.
  lease_duration_sec
    `lease_duration_sec` is the lifetime of the subscription. By default, this is set to 0 seconds and the subscription never expires.
unsubscribe(document_class, sub_id, topic=None)

  Remove a subscription. Expect a delay of a few seconds between when `unsubscribe()` returns successfully and when the subscription is removed and inactive. Once the last subscription for a given `topic` is removed, the `topic` also no longer exists.

  Arguments:

  document_class
    `document_class` is class derived from `db.Model`.
  sub_id
    `sub_id` is the unique string identifier for the subscription to be removed.
  topic
    `topic` specifies the namespace for the subscriptions to unsubscribe. Topics are set to the document's class name if not explicitly specified.