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 specifysimple
ornone
.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 specifysimple
ornone
.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/”.