Methods
Base API template. The API is an extended txtai application, adding the ability to cluster API instances together.
Downstream applications can extend this base template to add/modify functionality.
Source code in txtai/api/base.py
class API(Application):
"""
Base API template. The API is an extended txtai application, adding the ability to cluster API instances together.
Downstream applications can extend this base template to add/modify functionality.
"""
def __init__(self, config, loaddata=True):
super().__init__(config, loaddata)
# Embeddings cluster
self.cluster = None
if self.config.get("cluster"):
self.cluster = Cluster(self.config["cluster"])
# pylint: disable=W0221
def search(self, query, limit=None, weights=None, index=None, request=None):
# When search is invoked via the API, limit is set from the request
# When search is invoked directly, limit is set using the method parameter
limit = self.limit(request.query_params.get("limit") if request and hasattr(request, "query_params") else limit)
weights = self.weights(request.query_params.get("weights") if request and hasattr(request, "query_params") else weights)
index = request.query_params.get("index") if request and hasattr(request, "query_params") else index
if self.cluster:
return self.cluster.search(query, limit, weights, index)
return super().search(query, limit, weights, index)
def batchsearch(self, queries, limit=None, weights=None, index=None):
if self.cluster:
return self.cluster.batchsearch(queries, self.limit(limit), weights, index)
return super().batchsearch(queries, limit, weights, index)
def add(self, documents):
"""
Adds a batch of documents for indexing.
Downstream applications can override this method to also store full documents in an external system.
Args:
documents: list of {id: value, text: value}
Returns:
unmodified input documents
"""
if self.cluster:
self.cluster.add(documents)
else:
super().add(documents)
return documents
def index(self):
"""
Builds an embeddings index for previously batched documents.
"""
if self.cluster:
self.cluster.index()
else:
super().index()
def upsert(self):
"""
Runs an embeddings upsert operation for previously batched documents.
"""
if self.cluster:
self.cluster.upsert()
else:
super().upsert()
def delete(self, ids):
"""
Deletes from an embeddings index. Returns list of ids deleted.
Args:
ids: list of ids to delete
Returns:
ids deleted
"""
if self.cluster:
return self.cluster.delete(ids)
return super().delete(ids)
def reindex(self, config, function=None):
"""
Recreates this embeddings index using config. This method only works if document content storage is enabled.
Args:
config: new config
function: optional function to prepare content for indexing
"""
if self.cluster:
self.cluster.reindex(config, function)
else:
super().reindex(config, function)
def count(self):
"""
Total number of elements in this embeddings index.
Returns:
number of elements in embeddings index
"""
if self.cluster:
return self.cluster.count()
return super().count()
def limit(self, limit):
"""
Parses the number of results to return from the request. Allows range of 1-250, with a default of 10.
Args:
limit: limit parameter
Returns:
bounded limit
"""
# Return between 1 and 250 results, defaults to 10
return max(1, min(250, int(limit) if limit else 10))
def weights(self, weights):
"""
Parses the weights parameter from the request.
Args:
weights: weights parameter
Returns:
weights
"""
return float(weights) if weights else weights
add(self, documents)
Adds a batch of documents for indexing.
Downstream applications can override this method to also store full documents in an external system.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
documents |
list of {id: value, text: value} |
required |
Returns:
| Type | Description |
|---|---|
unmodified input documents |
Source code in txtai/api/base.py
def add(self, documents):
"""
Adds a batch of documents for indexing.
Downstream applications can override this method to also store full documents in an external system.
Args:
documents: list of {id: value, text: value}
Returns:
unmodified input documents
"""
if self.cluster:
self.cluster.add(documents)
else:
super().add(documents)
return documents
batchsearch(self, queries, limit=None, weights=None, index=None)
Finds documents most similar to the input queries. This method will run either an index search or an index + database search depending on if a database is available.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
queries |
input queries |
required | |
limit |
maximum results |
None |
|
weights |
hybrid score weights, if applicable |
None |
|
index |
index name, if applicable |
None |
Returns:
| Type | Description |
|---|---|
list of {id |
value, score: value} per query for index search, list of dict per query for an index + database search |
Source code in txtai/api/base.py
def batchsearch(self, queries, limit=None, weights=None, index=None):
if self.cluster:
return self.cluster.batchsearch(queries, self.limit(limit), weights, index)
return super().batchsearch(queries, limit, weights, index)
count(self)
Total number of elements in this embeddings index.
Returns:
| Type | Description |
|---|---|
number of elements in embeddings index |
Source code in txtai/api/base.py
def count(self):
"""
Total number of elements in this embeddings index.
Returns:
number of elements in embeddings index
"""
if self.cluster:
return self.cluster.count()
return super().count()
delete(self, ids)
Deletes from an embeddings index. Returns list of ids deleted.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ids |
list of ids to delete |
required |
Returns:
| Type | Description |
|---|---|
ids deleted |
Source code in txtai/api/base.py
def delete(self, ids):
"""
Deletes from an embeddings index. Returns list of ids deleted.
Args:
ids: list of ids to delete
Returns:
ids deleted
"""
if self.cluster:
return self.cluster.delete(ids)
return super().delete(ids)
index(self)
Builds an embeddings index for previously batched documents.
Source code in txtai/api/base.py
def index(self):
"""
Builds an embeddings index for previously batched documents.
"""
if self.cluster:
self.cluster.index()
else:
super().index()
limit(self, limit)
Parses the number of results to return from the request. Allows range of 1-250, with a default of 10.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
limit |
limit parameter |
required |
Returns:
| Type | Description |
|---|---|
bounded limit |
Source code in txtai/api/base.py
def limit(self, limit):
"""
Parses the number of results to return from the request. Allows range of 1-250, with a default of 10.
Args:
limit: limit parameter
Returns:
bounded limit
"""
# Return between 1 and 250 results, defaults to 10
return max(1, min(250, int(limit) if limit else 10))
reindex(self, config, function=None)
Recreates this embeddings index using config. This method only works if document content storage is enabled.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config |
new config |
required | |
function |
optional function to prepare content for indexing |
None |
Source code in txtai/api/base.py
def reindex(self, config, function=None):
"""
Recreates this embeddings index using config. This method only works if document content storage is enabled.
Args:
config: new config
function: optional function to prepare content for indexing
"""
if self.cluster:
self.cluster.reindex(config, function)
else:
super().reindex(config, function)
search(self, query, limit=None, weights=None, index=None, request=None)
Finds documents most similar to the input query. This method will run either an index search or an index + database search depending on if a database is available.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
query |
input query |
required | |
limit |
maximum results |
None |
|
weights |
hybrid score weights, if applicable |
None |
|
index |
index name, if applicable |
None |
Returns:
| Type | Description |
|---|---|
list of {id |
value, score: value} for index search, list of dict for an index + database search |
Source code in txtai/api/base.py
def search(self, query, limit=None, weights=None, index=None, request=None):
# When search is invoked via the API, limit is set from the request
# When search is invoked directly, limit is set using the method parameter
limit = self.limit(request.query_params.get("limit") if request and hasattr(request, "query_params") else limit)
weights = self.weights(request.query_params.get("weights") if request and hasattr(request, "query_params") else weights)
index = request.query_params.get("index") if request and hasattr(request, "query_params") else index
if self.cluster:
return self.cluster.search(query, limit, weights, index)
return super().search(query, limit, weights, index)
upsert(self)
Runs an embeddings upsert operation for previously batched documents.
Source code in txtai/api/base.py
def upsert(self):
"""
Runs an embeddings upsert operation for previously batched documents.
"""
if self.cluster:
self.cluster.upsert()
else:
super().upsert()
weights(self, weights)
Parses the weights parameter from the request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
weights |
weights parameter |
required |
Returns:
| Type | Description |
|---|---|
weights |
Source code in txtai/api/base.py
def weights(self, weights):
"""
Parses the weights parameter from the request.
Args:
weights: weights parameter
Returns:
weights
"""
return float(weights) if weights else weights