Google Cloud Platform
Hide
Python
Write Feedback

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 webapp2.
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, 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.
query
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.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.