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

  1. class API(Application):
  2.     """
  3.     Base API template. The API is an extended txtai application, adding the ability to cluster API instances together.
  5.     Downstream applications can extend this base template to add/modify functionality.
  6.     """
  8.     def __init__(self, config, loaddata=True):
  9.         super().__init__(config, loaddata)
  11.         # Embeddings cluster
  12.         self.cluster = None
  13.         if self.config.get("cluster"):
  14.             self.cluster = Cluster(self.config["cluster"])
  16.     # pylint: disable=W0221
  17.     def search(self, query, limit=None, weights=None, index=None, request=None):
  18.         # When search is invoked via the API, limit is set from the request
  19.         # When search is invoked directly, limit is set using the method parameter
  20.         limit = self.limit(request.query_params.get("limit") if request and hasattr(request, "query_params") else limit)
  21.         weights = self.weights(request.query_params.get("weights") if request and hasattr(request, "query_params") else weights)
  22.         index = request.query_params.get("index") if request and hasattr(request, "query_params") else index
  24.         if self.cluster:
  25.             return self.cluster.search(query, limit, weights, index)
  27.         return super().search(query, limit, weights, index)
  29.     def batchsearch(self, queries, limit=None, weights=None, index=None):
  30.         if self.cluster:
  31.             return self.cluster.batchsearch(queries, self.limit(limit), weights, index)
  33.         return super().batchsearch(queries, limit, weights, index)
  35.     def add(self, documents):
  36.         """
  37.         Adds a batch of documents for indexing.
  39.         Downstream applications can override this method to also store full documents in an external system.
  41.         Args:
  42.             documents: list of {id: value, text: value}
  44.         Returns:
  45.             unmodified input documents
  46.         """
  48.         if self.cluster:
  49.             self.cluster.add(documents)
  50.         else:
  51.             super().add(documents)
  53.         return documents
  55.     def index(self):
  56.         """
  57.         Builds an embeddings index for previously batched documents.
  58.         """
  60.         if self.cluster:
  61.             self.cluster.index()
  62.         else:
  63.             super().index()
  65.     def upsert(self):
  66.         """
  67.         Runs an embeddings upsert operation for previously batched documents.
  68.         """
  70.         if self.cluster:
  71.             self.cluster.upsert()
  72.         else:
  73.             super().upsert()
  75.     def delete(self, ids):
  76.         """
  77.         Deletes from an embeddings index. Returns list of ids deleted.
  79.         Args:
  80.             ids: list of ids to delete
  82.         Returns:
  83.             ids deleted
  84.         """
  86.         if self.cluster:
  87.             return self.cluster.delete(ids)
  89.         return super().delete(ids)
  91.     def reindex(self, config, function=None):
  92.         """
  93.         Recreates this embeddings index using config. This method only works if document content storage is enabled.
  95.         Args:
  96.             config: new config
  97.             function: optional function to prepare content for indexing
  98.         """
  100.         if self.cluster:
  101.             self.cluster.reindex(config, function)
  102.         else:
  103.             super().reindex(config, function)
  105.     def count(self):
  106.         """
  107.         Total number of elements in this embeddings index.
  109.         Returns:
  110.             number of elements in embeddings index
  111.         """
  113.         if self.cluster:
  114.             return self.cluster.count()
  116.         return super().count()
  118.     def limit(self, limit):
  119.         """
  120.         Parses the number of results to return from the request. Allows range of 1-250, with a default of 10.
  122.         Args:
  123.             limit: limit parameter
  125.         Returns:
  126.             bounded limit
  127.         """
  129.         # Return between 1 and 250 results, defaults to 10
  130.         return max(1, min(250, int(limit) if limit else 10))
  132.     def weights(self, weights):
  133.         """
  134.         Parses the weights parameter from the request.
  136.         Args:
  137.             weights: weights parameter
  139.         Returns:
  140.             weights
  141.         """
  143.         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:

NameTypeDescriptionDefault
documents

list of {id: value, text: value}

required

Returns:

TypeDescription

unmodified input documents

Source code in txtai/api/base.py

  1. def add(self, documents):
  2.     """
  3.     Adds a batch of documents for indexing.
  5.     Downstream applications can override this method to also store full documents in an external system.
  7.     Args:
  8.         documents: list of {id: value, text: value}
  10.     Returns:
  11.         unmodified input documents
  12.     """
  14.     if self.cluster:
  15.         self.cluster.add(documents)
  16.     else:
  17.         super().add(documents)
  19.     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:

NameTypeDescriptionDefault
queries

input queries

required
limit

maximum results

None
weights

hybrid score weights, if applicable

None
index

index name, if applicable

None

Returns:

TypeDescription
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

  1. def batchsearch(self, queries, limit=None, weights=None, index=None):
  2.     if self.cluster:
  3.         return self.cluster.batchsearch(queries, self.limit(limit), weights, index)
  5.     return super().batchsearch(queries, limit, weights, index)

count(self)

Total number of elements in this embeddings index.

Returns:

TypeDescription

number of elements in embeddings index

Source code in txtai/api/base.py

  1. def count(self):
  2.     """
  3.     Total number of elements in this embeddings index.
  5.     Returns:
  6.         number of elements in embeddings index
  7.     """
  9.     if self.cluster:
  10.         return self.cluster.count()
  12.     return super().count()

delete(self, ids)

Deletes from an embeddings index. Returns list of ids deleted.

Parameters:

NameTypeDescriptionDefault
ids

list of ids to delete

required

Returns:

TypeDescription

ids deleted

Source code in txtai/api/base.py

  1. def delete(self, ids):
  2.     """
  3.     Deletes from an embeddings index. Returns list of ids deleted.
  5.     Args:
  6.         ids: list of ids to delete
  8.     Returns:
  9.         ids deleted
  10.     """
  12.     if self.cluster:
  13.         return self.cluster.delete(ids)
  15.     return super().delete(ids)

index(self)

Builds an embeddings index for previously batched documents.

Source code in txtai/api/base.py

  1. def index(self):
  2.     """
  3.     Builds an embeddings index for previously batched documents.
  4.     """
  6.     if self.cluster:
  7.         self.cluster.index()
  8.     else:
  9.         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:

NameTypeDescriptionDefault
limit

limit parameter

required

Returns:

TypeDescription

bounded limit

Source code in txtai/api/base.py

  1. def limit(self, limit):
  2.     """
  3.     Parses the number of results to return from the request. Allows range of 1-250, with a default of 10.
  5.     Args:
  6.         limit: limit parameter
  8.     Returns:
  9.         bounded limit
  10.     """
  12.     # Return between 1 and 250 results, defaults to 10
  13.     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:

NameTypeDescriptionDefault
config

new config

required
function

optional function to prepare content for indexing

None

Source code in txtai/api/base.py

  1. def reindex(self, config, function=None):
  2.     """
  3.     Recreates this embeddings index using config. This method only works if document content storage is enabled.
  5.     Args:
  6.         config: new config
  7.         function: optional function to prepare content for indexing
  8.     """
  10.     if self.cluster:
  11.         self.cluster.reindex(config, function)
  12.     else:
  13.         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:

NameTypeDescriptionDefault
query

input query

required
limit

maximum results

None
weights

hybrid score weights, if applicable

None
index

index name, if applicable

None

Returns:

TypeDescription
list of {id

value, score: value} for index search, list of dict for an index + database search

Source code in txtai/api/base.py

  1. def search(self, query, limit=None, weights=None, index=None, request=None):
  2.     # When search is invoked via the API, limit is set from the request
  3.     # When search is invoked directly, limit is set using the method parameter
  4.     limit = self.limit(request.query_params.get("limit") if request and hasattr(request, "query_params") else limit)
  5.     weights = self.weights(request.query_params.get("weights") if request and hasattr(request, "query_params") else weights)
  6.     index = request.query_params.get("index") if request and hasattr(request, "query_params") else index
  8.     if self.cluster:
  9.         return self.cluster.search(query, limit, weights, index)
  11.     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

  1. def upsert(self):
  2.     """
  3.     Runs an embeddings upsert operation for previously batched documents.
  4.     """
  6.     if self.cluster:
  7.         self.cluster.upsert()
  8.     else:
  9.         super().upsert()

weights(self, weights)

Parses the weights parameter from the request.

Parameters:

NameTypeDescriptionDefault
weights

weights parameter

required

Returns:

TypeDescription

weights

Source code in txtai/api/base.py

  1. def weights(self, weights):
  2.     """
  3.     Parses the weights parameter from the request.
  5.     Args:
  6.         weights: weights parameter
  8.     Returns:
  9.         weights
  10.     """
  12.     return float(weights) if weights else weights