Scout Client

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

class Scout(endpoint[, key=None])

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

Parameters:

• 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!')

get_indexes(**kwargs)

Return the list of indexes available on the server.

See Index list: “/” for more information.

create_index(name)

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_index(name)

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

get_index(name, **kwargs)

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:

Parameters:

• 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.

See Index detail: “/:index-name/” for more information.

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

Store a document in the specified index(es).

Parameters:

• 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_document([document_id=None[, content=None[, indexes=None[, metadata=None[, identifier=None[, attachments=None]]]]]])

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

Parameters:

• 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.

Note

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.

delete_document(document_id)

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

Parameters:document_id (int) – The integer document ID.

get_document(document_id)

Retrieve content for the given document.

Parameters:document_id (int) – The integer document ID.

get_documents(**kwargs)

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:

Parameters:

• 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.

See Document list: “/documents/” for more information.

attach_files(document_id, attachments)

Parameters:

• 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.

For more information, see Attachment list: “/documents/:document-id/attachments/”.

detach_file(document_id, filename)

Parameters:

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

Detach the specified file from the document.

update_file(document_id, filename, file_object)

Parameters:

• 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:

Parameters:

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

For more information, see Attachment list: “/documents/:document-id/attachments/”.

get_attachment(document_id, filename)

Retrieve data about the given attachment.

For more information, see Attachment detail: “/documents/:document-id/attachments/:filename/”.

download_attachment(document_id, filename)

Download the specified attachment.

For more information, see Attachment download: “/documents/:document-id/attachments/:filename/download/”.