Reference API¶
Create an Application Package¶
The first step to create a Vespa application is to create an instance of ApplicationPackage
.
-
class
vespa.package.
ApplicationPackage
(name: str, schema: Optional[vespa.package.Schema] = None, query_profile: Optional[vespa.package.QueryProfile] = None, query_profile_type: Optional[vespa.package.QueryProfileType] = None)¶ -
__init__
(name: str, schema: Optional[vespa.package.Schema] = None, query_profile: Optional[vespa.package.QueryProfile] = None, query_profile_type: Optional[vespa.package.QueryProfileType] = None) → None¶ Create a Vespa Application Package.
Check the Vespa documentation for more detailed information about application packages.
Parameters: - name – Application name.
- schema –
Schema
of the application. If None, an emptySchema
with the same name of the application will be created by default. - query_profile –
QueryProfile
of the application. If None, aQueryProfile
named default withQueryProfileType
named root will be created by default. - query_profile_type –
QueryProfileType
of the application. If None, a emptyQueryProfileType
named root will be created by default.
The easiest way to get started is to create a default application package:
>>> ApplicationPackage(name="test_app") ApplicationPackage('test_app', Schema('test_app', Document(None), None, None, []), QueryProfile(None), QueryProfileType(None))
It will create a default
Schema
,QueryProfile
andQueryProfileType
that you can then populate with specifics of your application.
-
add_model_ranking
(model_config: vespa.ml.ModelConfig, include_model_summary_features=False, **kwargs) → None¶ Add ranking profile based on a specific model config.
Parameters: - model_config – Model config instance specifying the model to be used on the RankProfile.
- include_model_summary_features – True to include model specific summary features, such as inputs and outputs that are useful for debugging. Default to False as this requires an extra model evaluation when fetching summary features.
- kwargs – Further arguments to be passed to RankProfile.
Returns: None
-
Schema and Document¶
An ApplicationPackage
instance comes with a default Schema
that contains a default Document
,
meaning that you usually do not need to create those yourself.
-
class
vespa.package.
Schema
(name: str, document: vespa.package.Document, fieldsets: Optional[List[vespa.package.FieldSet]] = None, rank_profiles: Optional[List[vespa.package.RankProfile]] = None, models: Optional[List[vespa.package.OnnxModel]] = None)¶ -
__init__
(name: str, document: vespa.package.Document, fieldsets: Optional[List[vespa.package.FieldSet]] = None, rank_profiles: Optional[List[vespa.package.RankProfile]] = None, models: Optional[List[vespa.package.OnnxModel]] = None) → None¶ Create a Vespa Schema.
Check the Vespa documentation for more detailed information about schemas.
Parameters: - name – Schema name.
- document – Vespa
Document
associated with the Schema. - fieldsets – A list of
FieldSet
associated with the Schema. - rank_profiles – A list of
RankProfile
associated with the Schema. - models – A list of
OnnxModel
associated with the Schema.
To create a Schema:
>>> Schema(name="schema_name", document=Document()) Schema('schema_name', Document(None), None, None, [])
-
add_field_set
(field_set: vespa.package.FieldSet) → None¶ Add a
FieldSet
to the Schema.Parameters: field_set – field sets to be added.
-
add_fields
(*fields) → None¶ Add
Field
to the Schema’sDocument
.Parameters: fields – fields to be added.
-
add_model
(model: vespa.package.OnnxModel) → None¶ Add a
OnnxModel
to the Schema. :param model: model to be added. :return: None.
-
add_rank_profile
(rank_profile: vespa.package.RankProfile) → None¶ Add a
RankProfile
to the Schema.Parameters: rank_profile – rank profile to be added. Returns: None.
-
-
class
vespa.package.
Document
(fields: Optional[List[vespa.package.Field]] = None)¶ -
__init__
(fields: Optional[List[vespa.package.Field]] = None) → None¶ Create a Vespa Document.
Check the Vespa documentation for more detailed information about documents.
Parameters: fields – A list of Field
to include in the document’s schema.To create a Document:
>>> Document() Document(None)
>>> Document(fields=[Field(name="title", type="string")]) Document([Field('title', 'string', None, None, None, None)])
-
Create a Field¶
Once we have an ApplicationPackage
instance containing a Schema
and a Document
we usually
want to add fields so that we can store our data in a structured manner. We can accomplish that by creating
Field
instances and adding those to the ApplicationPackage
instance via Schema
and
Document
methods.
-
class
vespa.package.
Field
(name: str, type: str, indexing: Optional[List[str]] = None, index: Optional[str] = None, attribute: Optional[List[str]] = None, ann: Optional[vespa.package.HNSW] = None)¶ -
__init__
(name: str, type: str, indexing: Optional[List[str]] = None, index: Optional[str] = None, attribute: Optional[List[str]] = None, ann: Optional[vespa.package.HNSW] = None) → None¶ Create a Vespa field.
Check the Vespa documentation for more detailed information about fields.
Parameters: - name – Field name.
- type – Field data type.
- indexing – Configures how to process data of a field during indexing.
- index – Sets index parameters. Content in fields with index are normalized and tokenized by default.
- attribute – Specifies a property of an index structure attribute.
- ann – Add configuration for approximate nearest neighbor.
>>> Field(name = "title", type = "string", indexing = ["index", "summary"], index = "enable-bm25") Field('title', 'string', ['index', 'summary'], 'enable-bm25', None, None)
>>> Field( ... name = "abstract", ... type = "string", ... indexing = ["attribute"], ... attribute=["fast-search", "fast-access"] ... ) Field('abstract', 'string', ['attribute'], None, ['fast-search', 'fast-access'], None)
>>> Field(name="tensor_field", ... type="tensor<float>(x[128])", ... indexing=["attribute"], ... ann=HNSW( ... distance_metric="enclidean", ... max_links_per_node=16, ... neighbors_to_explore_at_insert=200, ... ), ... ) Field('tensor_field', 'tensor<float>(x[128])', ['attribute'], None, None, HNSW('enclidean', 16, 200))
-
Create a FieldSet¶
-
class
vespa.package.
FieldSet
(name: str, fields: List[str])¶ -
__init__
(name: str, fields: List[str]) → None¶ Create a Vespa field set.
A fieldset groups fields together for searching. Check the Vespa documentation for more detailed information about field sets.
Parameters: - name – Name of the fieldset
- fields – Field names to be included in the fieldset.
>>> FieldSet(name="default", fields=["title", "body"]) FieldSet('default', ['title', 'body'])
-
Create a RankProfile¶
-
class
vespa.package.
RankProfile
(name: str, first_phase: str, inherits: Optional[str] = None, constants: Optional[Dict[KT, VT]] = None, functions: Optional[List[vespa.package.Function]] = None, summary_features: Optional[List[T]] = None, second_phase: Optional[vespa.package.SecondPhaseRanking] = None)¶ -
__init__
(name: str, first_phase: str, inherits: Optional[str] = None, constants: Optional[Dict[KT, VT]] = None, functions: Optional[List[vespa.package.Function]] = None, summary_features: Optional[List[T]] = None, second_phase: Optional[vespa.package.SecondPhaseRanking] = None) → None¶ Create a Vespa rank profile.
Rank profiles are used to specify an alternative ranking of the same data for different purposes, and to experiment with new rank settings. Check the Vespa documentation for more detailed information about rank profiles.
Parameters: - name – Rank profile name.
- first_phase – The config specifying the first phase of ranking. More info about first phase ranking.
- inherits – The inherits attribute is optional. If defined, it contains the name of one other rank profile in the same schema. Values not defined in this rank profile will then be inherited.
- constants –
Dict of constants available in ranking expressions, resolved and optimized at configuration time. More info about constants.
- functions – Optional list of
Function
representing rank functions to be included in the rank profile. - summary_features –
List of rank features to be included with each hit. More info about summary features.
- second_phase – Optional config specifying the second phase of ranking.
See
SecondPhaseRanking
.
>>> RankProfile(name = "default", first_phase = "nativeRank(title, body)") RankProfile('default', 'nativeRank(title, body)', None, None, None, None, None)
>>> RankProfile(name = "new", first_phase = "BM25(title)", inherits = "default") RankProfile('new', 'BM25(title)', 'default', None, None, None, None)
>>> RankProfile( ... name = "new", ... first_phase = "BM25(title)", ... inherits = "default", ... constants={"TOKEN_NONE": 0, "TOKEN_CLS": 101, "TOKEN_SEP": 102}, ... summary_features=["BM25(title)"] ... ) RankProfile('new', 'BM25(title)', 'default', {'TOKEN_NONE': 0, 'TOKEN_CLS': 101, 'TOKEN_SEP': 102}, None, ['BM25(title)'], None)
>>> RankProfile( ... name="bert", ... first_phase="bm25(title) + bm25(body)", ... second_phase=SecondPhaseRanking(expression="1.25 * bm25(title) + 3.75 * bm25(body)", rerank_count=10), ... inherits="default", ... constants={"TOKEN_NONE": 0, "TOKEN_CLS": 101, "TOKEN_SEP": 102}, ... functions=[ ... Function( ... name="question_length", ... expression="sum(map(query(query_token_ids), f(a)(a > 0)))" ... ), ... Function( ... name="doc_length", ... expression="sum(map(attribute(doc_token_ids), f(a)(a > 0)))" ... ) ... ], ... summary_features=["question_length", "doc_length"] ... ) RankProfile('bert', 'bm25(title) + bm25(body)', 'default', {'TOKEN_NONE': 0, 'TOKEN_CLS': 101, 'TOKEN_SEP': 102}, [Function('question_length', 'sum(map(query(query_token_ids), f(a)(a > 0)))', None), Function('doc_length', 'sum(map(attribute(doc_token_ids), f(a)(a > 0)))', None)], ['question_length', 'doc_length'], SecondPhaseRanking('1.25 * bm25(title) + 3.75 * bm25(body)', 10))
-
Query Profile¶
A QueryProfile
is a named collection of search request parameters given in the configuration. The search
request can specify a query profile whose parameters will be used as parameters of that request. The query profiles may
optionally be type checked. Type checking is turned on by referencing a QueryProfileType
from the query
profile.
An ApplicationPackage
instance comes with a default QueryProfile
named default that is associated
with a QueryProfileType
named root, meaning that you usually do not need to create those yourself, only add
fields to them when required.
Create a QueryProfileType¶
-
class
vespa.package.
QueryTypeField
(name: str, type: str)¶ -
__init__
(name: str, type: str) → None¶ Create a field to be included in a
QueryProfileType
.Parameters: - name – Field name.
- type – Field type.
>>> QueryTypeField( ... name="ranking.features.query(title_bert)", ... type="tensor<float>(x[768])" ... ) QueryTypeField('ranking.features.query(title_bert)', 'tensor<float>(x[768])')
-
-
class
vespa.package.
QueryProfileType
(fields: Optional[List[vespa.package.QueryTypeField]] = None)¶ -
__init__
(fields: Optional[List[vespa.package.QueryTypeField]] = None) → None¶ Create a Vespa Query Profile Type.
Check the Vespa documentation for more detailed information about query profile types.
Parameters: fields – A list of QueryTypeField
.>>> QueryProfileType( ... fields = [ ... QueryTypeField( ... name="ranking.features.query(tensor_bert)", ... type="tensor<float>(x[768])" ... ) ... ] ... ) QueryProfileType([QueryTypeField('ranking.features.query(tensor_bert)', 'tensor<float>(x[768])')])
-
add_fields
(*fields) → None¶ Add
QueryTypeField
’s to the Query Profile Type.Parameters: fields – fields to be added >>> query_profile_type = QueryProfileType() >>> query_profile_type.add_fields( ... QueryTypeField( ... name="age", ... type="integer" ... ), ... QueryTypeField( ... name="profession", ... type="string" ... ) ... )
-
Create a QueryProfile¶
-
class
vespa.package.
QueryField
(name: str, value: Union[str, int, float])¶ -
__init__
(name: str, value: Union[str, int, float]) → None¶ Create a field to be included in a
QueryProfile
.Parameters: - name – Field name.
- value – Field value.
>>> QueryField(name="maxHits", value=1000) QueryField('maxHits', 1000)
-
-
class
vespa.package.
QueryProfile
(fields: Optional[List[vespa.package.QueryField]] = None)¶ -
__init__
(fields: Optional[List[vespa.package.QueryField]] = None) → None¶ Create a Vespa Query Profile.
Check the Vespa documentation for more detailed information about query profiles.
Parameters: fields – A list of QueryField
.>>> QueryProfile(fields=[QueryField(name="maxHits", value=1000)]) QueryProfile([QueryField('maxHits', 1000)])
-
add_fields
(*fields) → None¶ Add
QueryField
’s to the Query Profile.Parameters: fields – fields to be added >>> query_profile = QueryProfile() >>> query_profile.add_fields(QueryField(name="maxHits", value=1000))
-
Deploying your application¶
-
class
vespa.package.
VespaDocker
(port: int = 8080, output_file: IO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)¶ -
__init__
(port: int = 8080, output_file: IO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>) → None¶ Manage Docker deployments. :param output_file: Output file to write output messages.
-
deploy
(application_package: vespa.package.ApplicationPackage, disk_folder: str, container_memory: str = '4G') → vespa.application.Vespa¶ Deploy the application package into a Vespa container. :param application_package: ApplicationPackage to be deployed. :param disk_folder: Disk folder to save the required Vespa config files. :param container_memory: Docker container memory available to the application. :return: a Vespa connection instance.
-
deploy_from_disk
(application_name: str, disk_folder: str, container_memory: str = '4G', application_folder: Optional[str] = None) → vespa.application.Vespa¶ Deploy disk-based application package into a Vespa container. :param application_name: Name of the application. :param disk_folder: The disk_folder will be mapped to the /app directory inside the Docker container. :param container_memory: Docker container memory available to the application. :param application_folder: The folder inside disk_folder containing the application files. If None,
we assume disk_folder to be the application folder.Returns: a Vespa connection instance.
-
static
export_application_package
(disk_folder: str, application_package: vespa.package.ApplicationPackage) → None¶ Export application package to disk. :param disk_folder: Desired application path. Directory will be created if not already exist. :param application_package: Application package to export. :return: None. Application package file will be stored on disk_folder.
-
restart_services
()¶ Restart Vespa services.
Returns: None
-
start_services
()¶ Start Vespa services.
Returns: None
-
stop_services
()¶ Stop Vespa services.
Returns: None
-
-
class
vespa.package.
VespaCloud
(tenant: str, application: str, application_package: vespa.package.ApplicationPackage, key_location: Optional[str] = None, key_content: Optional[str] = None, output_file: IO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)¶ -
__init__
(tenant: str, application: str, application_package: vespa.package.ApplicationPackage, key_location: Optional[str] = None, key_content: Optional[str] = None, output_file: IO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>) → None¶ Deploy application to the Vespa Cloud (cloud.vespa.ai)
Parameters: - tenant – Tenant name registered in the Vespa Cloud.
- application – Application name registered in the Vespa Cloud.
- application_package – ApplicationPackage to be deployed.
- key_location – Location of the private key used for signing HTTP requests to the Vespa Cloud.
- key_content – Content of the private key used for signing HTTP requests to the Vespa Cloud. Use only when key file is not available.
- output_file – Output file to write output messages.
-
delete
(instance: str)¶ Delete the specified instance from the dev environment in the Vespa Cloud. :param instance: Name of the instance to delete. :return:
-
deploy
(instance: str, disk_folder: str) → vespa.application.Vespa¶ Deploy the given application package as the given instance in the Vespa Cloud dev environment.
Parameters: - instance – Name of this instance of the application, in the Vespa Cloud.
- disk_folder – Disk folder to save the required Vespa config files.
Returns: a Vespa connection instance.
-
vespa.application module¶
-
class
vespa.application.
Vespa
(url: str, port: Optional[int] = None, deployment_message: Optional[List[str]] = None, cert: Optional[str] = None, output_file: IO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)¶ Bases:
object
-
__init__
(url: str, port: Optional[int] = None, deployment_message: Optional[List[str]] = None, cert: Optional[str] = None, output_file: IO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>) → None¶ Establish a connection with a Vespa application.
Parameters: - url – Vespa instance URL.
- port – Vespa instance port.
- deployment_message – Message returned by Vespa engine after deployment. Used internally by deploy methods.
- cert – Path to certificate and key file.
- output_file – Output file to write output messages.
>>> Vespa(url = "https://cord19.vespa.ai") # doctest: +SKIP
>>> Vespa(url = "http://localhost", port = 8080) Vespa(http://localhost, 8080)
>>> Vespa(url = "https://api.vespa-external.aws.oath.cloud", port = 4443, cert = "/path/to/cert-and-key.pem") # doctest: +SKIP
-
static
annotate_data
(hits, query_id, id_field, relevant_id, fields, relevant_score, default_score)¶
-
collect_training_data
(labeled_data: List[Dict[KT, VT]], id_field: str, query_model: vespa.query.QueryModel, number_additional_docs: int, relevant_score: int = 1, default_score: int = 0, show_progress: Optional[int] = None, **kwargs) → pandas.core.frame.DataFrame¶ Collect training data based on a set of labelled data.
Parameters: - labeled_data – Labelled data containing query, query_id and relevant ids.
- id_field – The Vespa field representing the document id.
- query_model – Query model.
- number_additional_docs – Number of additional documents to retrieve for each relevant document.
- relevant_score – Score to assign to relevant documents. Default to 1.
- default_score – Score to assign to the additional documents that are not relevant. Default to 0.
- show_progress – Prints the the current point being collected every show_progress step. Default to None, in which case progress is not printed.
- kwargs – Extra keyword arguments to be included in the Vespa Query.
Returns: DataFrame containing document id (document_id), query id (query_id), scores (relevant) and vespa rank features returned by the Query model RankProfile used.
-
collect_training_data_point
(query: str, query_id: str, relevant_id: str, id_field: str, query_model: vespa.query.QueryModel, number_additional_docs: int, fields: List[str], relevant_score: int = 1, default_score: int = 0, **kwargs) → List[Dict[KT, VT]]¶ Collect training data based on a single query
Parameters: - query – Query string.
- query_id – Query id represented as str.
- relevant_id – Relevant id represented as a str.
- id_field – The Vespa field representing the document id.
- query_model – Query model.
- number_additional_docs – Number of additional documents to retrieve for each relevant document.
- fields – Which fields should be retrieved.
- relevant_score – Score to assign to relevant documents. Default to 1.
- default_score – Score to assign to the additional documents that are not relevant. Default to 0.
- kwargs – Extra keyword arguments to be included in the Vespa Query.
Returns: List of dicts containing the document id (document_id), query id (query_id), scores (relevant) and vespa rank features returned by the Query model RankProfile used.
-
delete_data
(schema: str, data_id: str) → requests.models.Response¶ Delete a data point from a Vespa app.
Parameters: - schema – The schema that we are deleting data from.
- data_id – Unique id associated with this data point.
Returns: Response of the HTTP DELETE request.
-
evaluate
(labeled_data: List[Dict[KT, VT]], eval_metrics: List[vespa.evaluation.EvalMetric], query_model: vespa.query.QueryModel, id_field: str, default_score: int = 0, **kwargs) → pandas.core.frame.DataFrame¶ Parameters: - labeled_data – Labelled data containing query, query_id and relevant ids.
- eval_metrics – A list of evaluation metrics.
- query_model – Query model.
- id_field – The Vespa field representing the document id.
- default_score – Score to assign to the additional documents that are not relevant. Default to 0.
- kwargs – Extra keyword arguments to be included in the Vespa Query.
Returns: DataFrame containing query_id and metrics according to the selected evaluation metrics.
-
evaluate_query
(eval_metrics: List[vespa.evaluation.EvalMetric], query_model: vespa.query.QueryModel, query_id: str, query: str, id_field: str, relevant_docs: List[Dict[KT, VT]], default_score: int = 0, **kwargs) → Dict[KT, VT]¶ Evaluate a query according to evaluation metrics
Parameters: - eval_metrics – A list of evaluation metrics.
- query_model – Query model.
- query_id – Query id represented as str.
- query – Query string.
- id_field – The Vespa field representing the document id.
- relevant_docs – A list with dicts where each dict contains a doc id a optionally a doc score.
- default_score – Score to assign to the additional documents that are not relevant. Default to 0.
- kwargs – Extra keyword arguments to be included in the Vespa Query.
Returns: Dict containing query_id and metrics according to the selected evaluation metrics.
-
feed_data_point
(schema: str, data_id: str, fields: Dict[KT, VT]) → requests.models.Response¶ Feed a data point to a Vespa app.
Parameters: - schema – The schema that we are sending data to.
- data_id – Unique id associated with this data point.
- fields – Dict containing all the fields required by the schema.
Returns: Response of the HTTP POST request.
-
get_application_status
() → Optional[requests.models.Response]¶ Get application status.
Returns:
-
get_data
(schema: str, data_id: str) → requests.models.Response¶ Get a data point from a Vespa app.
Parameters: - schema – The schema that we are getting data from.
- data_id – Unique id associated with this data point.
Returns: Response of the HTTP GET request.
-
query
(body: Optional[Dict[KT, VT]] = None, query: Optional[str] = None, query_model: Optional[vespa.query.QueryModel] = None, debug_request: bool = False, recall: Optional[Tuple] = None, **kwargs) → vespa.query.VespaResult¶ Send a query request to the Vespa application.
Either send ‘body’ containing all the request parameters or specify ‘query’ and ‘query_model’.
Parameters: - body – Dict containing all the request parameters.
- query – Query string
- query_model – Query model
- debug_request – return request body for debugging instead of sending the request.
- recall – Tuple of size 2 where the first element is the name of the field to use to recall and the second element is a list of the values to be recalled.
- kwargs – Additional parameters to be sent along the request.
Returns: Either the request body if debug_request is True or the result from the Vespa application
-
update_data
(schema: str, data_id: str, fields: Dict[KT, VT], create: bool = False) → requests.models.Response¶ Update a data point in a Vespa app.
Parameters: - schema – The schema that we are updating data.
- data_id – Unique id associated with this data point.
- fields – Dict containing all the fields you want to update.
- create – If true, updates to non-existent documents will create an empty document to update
Returns: Response of the HTTP PUT request.
-
vespa.evaluation module¶
-
class
vespa.evaluation.
EvalMetric
¶ Bases:
object
-
__init__
() → None¶ Initialize self. See help(type(self)) for accurate signature.
-
evaluate_query
(query_results, relevant_docs, id_field, default_score) → Dict[KT, VT]¶
-
-
class
vespa.evaluation.
MatchRatio
¶ Bases:
vespa.evaluation.EvalMetric
-
__init__
() → None¶ Computes the ratio of documents retrieved by the match phase.
-
evaluate_query
(query_results: vespa.query.VespaResult, relevant_docs: List[Dict[KT, VT]], id_field: str, default_score: int) → Dict[KT, VT]¶ Evaluate query results.
Parameters: - query_results – Raw query results returned by Vespa.
- relevant_docs – A list with dicts where each dict contains a doc id a optionally a doc score.
- id_field – The Vespa field representing the document id.
- default_score – Score to assign to the additional documents that are not relevant. Default to 0.
Returns: Dict containing the number of retrieved docs (_retrieved_docs), the number of docs available in the corpus (_docs_available) and the match ratio (_value).
-
-
class
vespa.evaluation.
NormalizedDiscountedCumulativeGain
(at: int)¶ Bases:
vespa.evaluation.EvalMetric
-
__init__
(at: int)¶ Compute the normalized discounted cumulative gain at position at
Parameters: at – Maximum position on the resulting list to look for relevant docs.
-
evaluate_query
(query_results: vespa.query.VespaResult, relevant_docs: List[Dict[KT, VT]], id_field: str, default_score: int) → Dict[KT, VT]¶ Evaluate query results.
Parameters: - query_results – Raw query results returned by Vespa.
- relevant_docs – A list with dicts where each dict contains a doc id a optionally a doc score.
- id_field – The Vespa field representing the document id.
- default_score – Score to assign to the additional documents that are not relevant. Default to 0.
Returns: Dict containing the ideal discounted cumulative gain (_ideal_dcg), the discounted cumulative gain (_dcg) and the normalized discounted cumulative gain (_value).
-
-
class
vespa.evaluation.
Recall
(at: int)¶ Bases:
vespa.evaluation.EvalMetric
-
__init__
(at: int) → None¶ Compute the recall at position at
Parameters: at – Maximum position on the resulting list to look for relevant docs.
-
evaluate_query
(query_results: vespa.query.VespaResult, relevant_docs: List[Dict[KT, VT]], id_field: str, default_score: int) → Dict[KT, VT]¶ Evaluate query results.
Parameters: - query_results – Raw query results returned by Vespa.
- relevant_docs – A list with dicts where each dict contains a doc id a optionally a doc score.
- id_field – The Vespa field representing the document id.
- default_score – Score to assign to the additional documents that are not relevant. Default to 0.
Returns: Dict containing the recall value (_value).
-
-
class
vespa.evaluation.
ReciprocalRank
(at: int)¶ Bases:
vespa.evaluation.EvalMetric
-
__init__
(at: int)¶ Compute the reciprocal rank at position at
Parameters: at – Maximum position on the resulting list to look for relevant docs.
-
evaluate_query
(query_results: vespa.query.VespaResult, relevant_docs: List[Dict[KT, VT]], id_field: str, default_score: int) → Dict[KT, VT]¶ Evaluate query results.
Parameters: - query_results – Raw query results returned by Vespa.
- relevant_docs – A list with dicts where each dict contains a doc id a optionally a doc score.
- id_field – The Vespa field representing the document id.
- default_score – Score to assign to the additional documents that are not relevant. Default to 0.
Returns: Dict containing the reciprocal rank value (_value).
-
vespa.query module¶
-
class
vespa.query.
AND
¶ Bases:
vespa.query.MatchFilter
-
__init__
() → None¶ Filter that match document containing all the query terms.
-
create_match_filter
(query: str) → str¶ Create part of the YQL expression related to the filter.
Parameters: query – Query input. Returns: Part of the YQL expression related to the filter.
-
get_query_properties
(query: Optional[str] = None) → Dict[KT, VT]¶ Relevant request properties associated with the filter.
Parameters: query – Query input. Returns: dict containing the relevant request properties associated with the filter.
-
-
class
vespa.query.
ANN
(doc_vector: str, query_vector: str, hits: int, label: str, approximate: bool = True)¶ Bases:
vespa.query.MatchFilter
-
__init__
(doc_vector: str, query_vector: str, hits: int, label: str, approximate: bool = True) → None¶ Match documents according to the nearest neighbor operator.
Reference: https://docs.vespa.ai/documentation/reference/query-language-reference.html#nearestneighbor
Parameters: - doc_vector – Name of the document field to be used in the distance calculation.
- query_vector – Name of the query field to be used in the distance calculation.
- hits – Lower bound on the number of hits to return.
- label – A label to identify this specific operator instance.
- approximate – True to use approximate nearest neighbor and False to use brute force. Default to True.
-
create_match_filter
(query: str) → str¶ Create part of the YQL expression related to the filter.
Parameters: query – Query input. Returns: Part of the YQL expression related to the filter.
-
get_query_properties
(query: Optional[str] = None) → Dict[str, str]¶ Relevant request properties associated with the filter.
Parameters: query – Query input. Returns: dict containing the relevant request properties associated with the filter.
-
-
class
vespa.query.
MatchFilter
¶ Bases:
object
Abstract class for match filters.
-
create_match_filter
(query: str) → str¶ Create part of the YQL expression related to the filter.
Parameters: query – Query input. Returns: Part of the YQL expression related to the filter.
-
get_query_properties
(query: Optional[str] = None) → Dict[KT, VT]¶ Relevant request properties associated with the filter.
Parameters: query – Query input. Returns: dict containing the relevant request properties associated with the filter.
-
-
class
vespa.query.
OR
¶ Bases:
vespa.query.MatchFilter
-
__init__
() → None¶ Filter that match any document containing at least one query term.
-
create_match_filter
(query: str) → str¶ Create part of the YQL expression related to the filter.
Parameters: query – Query input. Returns: Part of the YQL expression related to the filter.
-
get_query_properties
(query: Optional[str] = None) → Dict[KT, VT]¶ Relevant request properties associated with the filter.
Parameters: query – Query input. Returns: dict containing the relevant request properties associated with the filter.
-
-
class
vespa.query.
QueryModel
(query_properties: Optional[List[vespa.query.QueryProperty]] = None, match_phase: vespa.query.MatchFilter = <vespa.query.AND object>, rank_profile: vespa.query.RankProfile = <vespa.query.RankProfile object>)¶ Bases:
object
-
__init__
(query_properties: Optional[List[vespa.query.QueryProperty]] = None, match_phase: vespa.query.MatchFilter = <vespa.query.AND object>, rank_profile: vespa.query.RankProfile = <vespa.query.RankProfile object>) → None¶ Define a query model.
Parameters: - query_properties – Optional list of QueryProperty.
- match_phase – Define the match criteria. One of the MatchFilter options available.
- rank_profile – Define the rank criteria.
-
create_body
(query: str) → Dict[str, str]¶ Create the appropriate request body to be sent to Vespa.
Parameters: query – Query input. Returns: dict representing the request body.
-
-
class
vespa.query.
QueryProperty
¶ Bases:
object
Abstract class for query property.
-
get_query_properties
(query: Optional[str] = None) → Dict[KT, VT]¶ Extract query property syntax.
Parameters: query – Query input. Returns: dict containing the relevant request properties to be included in the query.
-
-
class
vespa.query.
QueryRankingFeature
(name: str, mapping: Callable[[str], List[float]])¶ Bases:
vespa.query.QueryProperty
-
__init__
(name: str, mapping: Callable[[str], List[float]]) → None¶ Include ranking.feature.query into a Vespa query.
Parameters: - name – Name of the feature.
- mapping – Function mapping a string to a list of floats.
-
get_query_properties
(query: Optional[str] = None) → Dict[str, str]¶ Extract query property syntax.
Parameters: query – Query input. Returns: dict containing the relevant request properties to be included in the query.
-
-
class
vespa.query.
RankProfile
(name: str = 'default', list_features: bool = False)¶ Bases:
object
-
__init__
(name: str = 'default', list_features: bool = False) → None¶ Define a rank profile.
Parameters: - name – Name of the rank profile as defined in a Vespa search definition.
- list_features – Should the ranking features be returned. Either ‘true’ or ‘false’.
-
-
class
vespa.query.
Union
(*args)¶ Bases:
vespa.query.MatchFilter
-
__init__
(*args) → None¶ Match documents that belongs to the union of many match filters.
Parameters: args – Match filters to be taken the union of.
-
create_match_filter
(query: str) → str¶ Create part of the YQL expression related to the filter.
Parameters: query – Query input. Returns: Part of the YQL expression related to the filter.
-
get_query_properties
(query: Optional[str] = None) → Dict[str, str]¶ Relevant request properties associated with the filter.
Parameters: query – Query input. Returns: dict containing the relevant request properties associated with the filter.
-
-
class
vespa.query.
VespaResult
(vespa_result, request_body=None)¶ Bases:
object
-
__init__
(vespa_result, request_body=None)¶ Initialize self. See help(type(self)) for accurate signature.
-
hits
¶
-
json
¶
-
number_documents_indexed
¶
-
number_documents_retrieved
¶
-
request_body
¶
-
-
class
vespa.query.
WeakAnd
(hits: int, field: str = 'default')¶ Bases:
vespa.query.MatchFilter
-
__init__
(hits: int, field: str = 'default') → None¶ Match documents according to the weakAND algorithm.
Reference: https://docs.vespa.ai/documentation/using-wand-with-vespa.html
Parameters: - hits – Lower bound on the number of hits to be retrieved.
- field – Which Vespa field to search.
-
create_match_filter
(query: str) → str¶ Create part of the YQL expression related to the filter.
Parameters: query – Query input. Returns: Part of the YQL expression related to the filter.
-
get_query_properties
(query: Optional[str] = None) → Dict[KT, VT]¶ Relevant request properties associated with the filter.
Parameters: query – Query input. Returns: dict containing the relevant request properties associated with the filter.
-