Prospective Search Functions (Python)

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.