Scout Client¶

Scout comes with a simple Python client. This document describes the client API.

The Scout class provides a simple, Pythonic API for interacting with and querying a Scout server.

• endpoint – The base URL the Scout server is running on.
• key – The authentication key (if used) required to access the Scout server.

Example of initializing the client:

>>> from scout_client import Scout >>> scout = Scout('https://search.my-site.com/', key='secret!') 

Return the list of indexes available on the server.

See Index list: “/” for more information.

Create a new index with the given name. If an index with that name already exists, you will receive a 400 response.

See the POST section of Index list: “/” for more information.

rename_index ( old_name , new_name ) ¶

Rename an existing index.

Delete an existing index. Any documents associated with the index will not be deleted.

Return the details about the particular index, along with a paginated list of all documents stored in the given index.

The following optional parameters are supported:

• q – full-text search query to be run over the documents in this index.
• ordering – columns to sort results by. By default, when you perform a search the results will be ordered by relevance.
• ranking – ranking algorithm to use. By default this is bm25 , however you can specify simple or none .
• page – page number of results to retrieve
• **filters – Arbitrary key/value pairs used to filter the metadata.

The Filtering on Metadata section describes how to use key/value pairs t construct filters on the document’s metadata.

create_document ( content , indexes [ , identifier=None [ , attachments=None [ , **metadata ] ] ] ) ¶

Store a document in the specified index(es).

• content (str) – Text content to expose for search.
• indexes – Either the name of an index or a list of index names.
• identifier – Optional alternative user-defined identifier for document.
• attachments – An optional mapping of filename to file-like object, which should be uploaded and stored as attachments on the given document.
• metadata – Arbitrary key/value pairs to store alongside the document content.

Update one or more attributes of a document that’s stored in the database.

• document_id (int) – The integer document ID (required).
• content (str) – Text content to expose for search (optional).
• indexes – Either the name of an index or a list of index names (optional).
• metadata – Arbitrary key/value pairs to store alongside the document content (optional).
• identifier – Optional alternative user-defined identifier for document.
• attachments – An optional mapping of filename to file-like object, which should be uploaded and stored as attachments on the given document. If a filename already exists, it will be over-written with the new attachment.

If you specify metadata when updating a document, existing metadata will be replaced by the new metadata. To simply clear out the metadata for an existing document, pass an empty dict .

Remove a document from the database, as well as all indexes.

document_id (int) – The integer document ID.

Retrieve content for the given document.

document_id (int) – The integer document ID.

Retrieve a paginated list of all documents in the database, regardless of index. This method can also be used to perform full-text search queries across the entire database of documents, or a subset of indexes.

The following optional parameters are supported:

• q – full-text search query to be run over the documents in this index.
• ordering – columns to sort results by. By default, when you perform a search the results will be ordered by relevance.
• index – one or more index names to restrict the results to.
• ranking – ranking algorithm to use. By default this is bm25 , however you can specify simple or none .
• page – page number of results to retrieve
• **filters – Arbitrary key/value pairs used to filter the metadata.

The Filtering on Metadata section describes how to use key/value pairs t construct filters on the document’s metadata.

• document_id – The integer ID of the document.
• attachments – A dictionary mapping filename to file-like object.

Upload the attachments and associate them with the given document.

• document_id – The integer ID of the document.
• filename – The filename of the attachment to remove.

Detach the specified file from the document.

• document_id – The integer ID of the document.
• filename – The filename of the attachment to update.
• file_object – A file-like object.

Replace the contents of the current attachment with the contents of file_object .

get_attachments ( document_id , ** kwargs ) ¶

Retrieve a paginated list of attachments associated with the given document.

The following optional parameters are supported:

• ordering – columns to use when sorting attachments.
• page – page number of results to retrieve

get_attachment ( document_id , filename ) ¶

Retrieve data about the given attachment.

download_attachment ( document_id , filename ) ¶

Download the specified attachment.