Reference API

ApplicationPackage

class vespa.package.ApplicationPackage(name: str, schema: Optional[List[vespa.package.Schema]] = None, query_profile: Optional[vespa.package.QueryProfile] = None, query_profile_type: Optional[vespa.package.QueryProfileType] = None, stateless_model_evaluation: bool = False, create_schema_by_default: bool = True, create_query_profile_by_default: bool = True, configurations: Optional[List[vespa.package.ApplicationConfiguration]] = None, validations: Optional[List[vespa.package.Validation]] = None)
__init__(name: str, schema: Optional[List[vespa.package.Schema]] = None, query_profile: Optional[vespa.package.QueryProfile] = None, query_profile_type: Optional[vespa.package.QueryProfileType] = None, stateless_model_evaluation: bool = False, create_schema_by_default: bool = True, create_query_profile_by_default: bool = True, configurations: Optional[List[vespa.package.ApplicationConfiguration]] = None, validations: Optional[List[vespa.package.Validation]] = None) → None

Create an Application Package. An ApplicationPackage instance comes with a default Schema that contains a default Document

Parameters:
  • name – Application name. Cannot contain ‘-’ or ‘_’.
  • schema – List of Schema`s of the application. If `None, an empty Schema with the same name of the application will be created by default.
  • query_profileQueryProfile of the application. If None, a QueryProfile named default with QueryProfileType named root will be created by default.
  • query_profile_typeQueryProfileType of the application. If None, a empty QueryProfileType named root will be created by default.
  • stateless_model_evaluation – Enable stateless model evaluation. Default to False.
  • create_schema_by_default – Include a Schema with the same name as the application if no Schema is provided in the schema argument.
  • create_query_profile_by_default – Include a default QueryProfile and QueryProfileType in case it is not explicitly defined by the user in the query_profile and query_profile_type parameters.
  • configurations – List of ApplicationConfiguration that contains configurations for the application.
  • validations – Optional list of Validation to be overridden.

The easiest way to get started is to create a default application package:

>>> ApplicationPackage(name="testapp")
ApplicationPackage('testapp', [Schema('testapp', Document(None, None, None), None, None, [], False, None, [])], QueryProfile(None), QueryProfileType(None))

It will create a default Schema, QueryProfile and QueryProfileType that you can then populate with specifics of your application.

add_schema(*schemas) → None

Add Schema’s to the application package.

Parameters:schemas – schemas to be added
Returns:
to_files(root: pathlib.Path) → None

Export the application package as a directory tree.

Parameters:root – Directory to export files to
Returns:
to_zip() → _io.BytesIO

Return the application package as zipped bytes, to be used in a subsequent deploy :return: BytesIO buffer

to_zipfile(zfile: pathlib.Path) → None

Export the application package as a deployable zipfile. See application packages for deployment options.

Parameters:zfile – Filename to export to
Returns:

Schema

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, global_document: bool = False, imported_fields: Optional[List[vespa.package.ImportedField]] = None, document_summaries: Optional[List[vespa.package.DocumentSummary]] = 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, global_document: bool = False, imported_fields: Optional[List[vespa.package.ImportedField]] = None, document_summaries: Optional[List[vespa.package.DocumentSummary]] = 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.
  • global_document – Set to True to copy the documents to all content nodes. Default to False.
  • imported_fields – A list of ImportedField defining fields from global documents to be imported.
  • document_summaries – A list of DocumentSummary associated with the schema.

To create a Schema:

>>> Schema(name="schema_name", document=Document())
Schema('schema_name', Document(None, None, None), None, None, [], False, None, [])
add_document_summary(document_summary: vespa.package.DocumentSummary) → None

Add a DocumentSummary to the Schema.

Parameters:document_summary – document summary to be added.
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’s Document.

Parameters:fields – fields to be added.
add_imported_field(imported_field: vespa.package.ImportedField) → None

Add a ImportedField to the Schema.

Parameters:imported_field – imported field 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.

Document

class vespa.package.Document(fields: Optional[List[vespa.package.Field]] = None, inherits: Optional[str] = None, structs: Optional[List[vespa.package.Struct]] = None)
__init__(fields: Optional[List[vespa.package.Field]] = None, inherits: Optional[str] = None, structs: Optional[List[vespa.package.Struct]] = 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, None, None)
>>> Document(fields=[Field(name="title", type="string")])
Document([Field('title', 'string', None, None, None, None, None, None, None, None, None, None, None, [])], None, None)
>>> Document(fields=[Field(name="title", type="string")], inherits="context")
Document([Field('title', 'string', None, None, None, None, None, None, None, None, None, None, None, [])], context, None)
add_fields(*fields) → None

Add Field’s to the document.

Parameters:fields – fields to be added
Returns:
add_structs(*structs) → None

Add Struct’s to the document.

Parameters:structs – structs to be added
Returns:

Field

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, match: Optional[List[Union[str, Tuple[str, str]]]] = None, weight: Optional[int] = None, bolding: Optional[Literal[True]] = None, summary: Optional[vespa.package.Summary] = None, **kwargs)
__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, match: Optional[List[Union[str, Tuple[str, str]]]] = None, weight: Optional[int] = None, bolding: Optional[Literal[True]] = None, summary: Optional[vespa.package.Summary] = None, **kwargs) → None

Create a Vespa field.

Check the Vespa documentation for more detailed information about fields.

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.

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.
  • match – Set properties that decide how the matching method for this field operate.
  • weight – Sets the weight of the field, using when calculating Rank Scores.
  • bolding – Whether to highlight matching query terms in the summary.
  • summary – Add configuration for summary of the field.
Key stemming:

Add configuration for stemming of the field.

Key rank:

Add configuration for ranking calculations of the field.

Key query_command:
 

Add configuration for query-command of the field.

Key struct_fields:
 

Add struct-fields to the field.

>>> Field(name = "title", type = "string", indexing = ["index", "summary"], index = "enable-bm25")
Field('title', 'string', ['index', 'summary'], 'enable-bm25', None, None, None, None, None, None, None, None, None, [])
>>> Field(
...     name = "abstract",
...     type = "string",
...     indexing = ["attribute"],
...     attribute=["fast-search", "fast-access"]
... )
Field('abstract', 'string', ['attribute'], None, ['fast-search', 'fast-access'], None, None, None, None, None, None, None, None, [])
>>> Field(name="tensor_field",
...     type="tensor<float>(x[128])",
...     indexing=["attribute"],
...     ann=HNSW(
...         distance_metric="euclidean",
...         max_links_per_node=16,
...         neighbors_to_explore_at_insert=200,
...     ),
... )
Field('tensor_field', 'tensor<float>(x[128])', ['attribute'], None, None, HNSW('euclidean', 16, 200), None, None, None, None, None, None, None, [])
>>> Field(
...     name = "abstract",
...     type = "string",
...     match = ["exact", ("exact-terminator", '"@%"',)],
... )
Field('abstract', 'string', None, None, None, None, ['exact', ('exact-terminator', '"@%"')], None, None, None, None, None, None, [])
>>> Field(
...     name = "abstract",
...     type = "string",
...     weight = 200,
... )
Field('abstract', 'string', None, None, None, None, None, 200, None, None, None, None, None, [])
>>> Field(
...     name = "abstract",
...     type = "string",
...     bolding = True,
... )
Field('abstract', 'string', None, None, None, None, None, None, True, None, None, None, None, [])
>>> Field(
...     name = "abstract",
...     type = "string",
...     summary = Summary(None, None, ["dynamic", ["bolding", "on"]]),
... )
Field('abstract', 'string', None, None, None, None, None, None, None, Summary(None, None, ['dynamic', ['bolding', 'on']]), None, None, None, [])
>>> Field(
...     name = "abstract",
...     type = "string",
...     stemming = "shortest",
... )
Field('abstract', 'string', None, None, None, None, None, None, None, None, 'shortest', None, None, [])
>>> Field(
...     name = "abstract",
...     type = "string",
...     rank = "filter",
... )
Field('abstract', 'string', None, None, None, None, None, None, None, None, None, 'filter', None, [])
>>> Field(
...     name = "abstract",
...     type = "string",
...     query_command = ['"exact %%"'],
... )
Field('abstract', 'string', None, None, None, None, None, None, None, None, None, None, ['"exact %%"'], [])
>>> Field(
...     name = "abstract",
...     type = "string",
...     struct_fields = [
...         StructField(
...             name = "first_name",
...             indexing = ["attribute"],
...             attribute = ["fast-search"],
...         ),
...     ],
... )
Field('abstract', 'string', None, None, None, None, None, None, None, None, None, None, None, [StructField('first_name', ['attribute'], ['fast-search'], None, None, None)])
add_struct_fields(*struct_fields) → None

Add StructField’s to the Field.

Parameters:struct_fields – struct-fields to be added

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'])

RankProfile

class vespa.package.RankProfile(name: str, first_phase: str, inherits: Optional[str] = None, constants: Optional[Dict] = None, functions: Optional[List[vespa.package.Function]] = None, summary_features: Optional[List] = None, second_phase: Optional[vespa.package.SecondPhaseRanking] = None, **kwargs)
__init__(name: str, first_phase: str, inherits: Optional[str] = None, constants: Optional[Dict] = None, functions: Optional[List[vespa.package.Function]] = None, summary_features: Optional[List] = None, second_phase: Optional[vespa.package.SecondPhaseRanking] = None, **kwargs) → 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 <https://docs.vespa.ai/en/reference/schema-reference.html#firstphase-rank>`__ 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 <https://docs.vespa.ai/en/reference/schema-reference.html#constants>`__ 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 <https://docs.vespa.ai/en/reference/schema-reference.html#summary-features>`__ about summary features.
  • second_phase – Optional config specifying the second phase of ranking. See SecondPhaseRanking.
Key weight:

A list of tuples containing the field and their weight

Key rank_type:

A list of tuples containing a field and the rank-type-name. More info <https://docs.vespa.ai/en/reference/schema-reference.html#rank-type>`__ about rank-type.

Key rank_properties:
 

A list of tuples containing a field and its configuration. More info <https://docs.vespa.ai/en/reference/schema-reference.html#rank-properties>`__ about rank-properties.

>>> RankProfile(name = "default", first_phase = "nativeRank(title, body)")
RankProfile('default', 'nativeRank(title, body)', None, None, None, None, None, None, None, None, None)
>>> RankProfile(name = "new", first_phase = "BM25(title)", inherits = "default")
RankProfile('new', 'BM25(title)', 'default', None, None, None, None, 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, None, None, None, 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), None, None, None, None)
>>> RankProfile(
...     name = "default",
...     first_phase = "nativeRank(title, body)",
...     weight = [("title", 200), ("body", 100)]
... )
RankProfile('default', 'nativeRank(title, body)', None, None, None, None, None, [('title', 200), ('body', 100)], None, None, None)
>>> RankProfile(
...     name = "default",
...     first_phase = "nativeRank(title, body)",
...     rank_type = [("body", "about")]
... )
RankProfile('default', 'nativeRank(title, body)', None, None, None, None, None, None, [('body', 'about')], None, None)
>>> RankProfile(
...     name = "default",
...     first_phase = "nativeRank(title, body)",
...     rank_properties = [("fieldMatch(title).maxAlternativeSegmentations", "10")]
... )
RankProfile('default', 'nativeRank(title, body)', None, None, None, None, None, None, None, [('fieldMatch(title).maxAlternativeSegmentations', '10')], None)

QueryProfile

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.

A QueryProfile is a named collection of query request parameters given in the configuration. The query 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.

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))

QueryField

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)

QueryProfileType

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.

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.

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"
...     )
... )

QueryTypeField

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])')

VespaDocker

class vespa.deployment.VespaDocker(port: int = 8080, container_memory: Union[str, int] = 4294967296, output_file: IO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, container: Optional[docker.models.containers.Container] = None, container_image: str = 'vespaengine/vespa', cfgsrv_port: int = 19071, debug_port: int = 5005)
__init__(port: int = 8080, container_memory: Union[str, int] = 4294967296, output_file: IO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, container: Optional[docker.models.containers.Container] = None, container_image: str = 'vespaengine/vespa', cfgsrv_port: int = 19071, debug_port: int = 5005) → None

Manage Docker deployments.

Parameters:
  • port – Container port.
  • cfgsrv_port – Config Server port.
  • debug_port – Port to connect to, to debug the vespa container.
  • output_file – Output file to write output messages.
  • container_memory – Docker container memory available to the application.
  • container – Used when instantiating VespaDocker from a running container.
  • container_image – Docker container image.
deploy(application_package: vespa.package.ApplicationPackage, debug: bool = False) → vespa.application.Vespa

Deploy the application package into a Vespa container. :param application_package: ApplicationPackage to be deployed. :param debug: Add the configured debug_port to the docker port mapping. :return: a Vespa connection instance.

deploy_from_disk(application_name: str, application_root: pathlib.Path, debug: bool = False) → vespa.application.Vespa

Deploy from a directory tree. Used when making changes to application package files not supported by pyvespa - this is why this method is not found in the ApplicationPackage class.

Parameters:
  • application_name – Application package name.
  • application_root – Application package directory root
  • debug – Add the configured debug_port to the docker port mapping.
Returns:

a Vespa connection instance.

static from_container_name_or_id(name_or_id: str, output_file: IO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>) → vespa.deployment.VespaDocker

Instantiate VespaDocker from a running container.

Parameters:
  • name_or_id – Name or id of the container.
  • output_file – Output file to write output messages.
Raises:

ValueError – Exception if container not found

Returns:

VespaDocker instance associated with the running container.

restart_services() → None

Restart Vespa services inside the docker image, it is equivalent to calling self.stop_services() followed by self.start_services().

Raises:RuntimeError – if a container has not been set
Returns:None
start_services() → None

Start Vespa services inside the docker image, first waiting for the Config Server, then for other services.

Raises:RuntimeError – if a container has not been set
Returns:None
stop_services() → None

Stop Vespa services inside the docker image, first stopping the services, then stopping the Config Server.

Raises:RuntimeError – if a container has not been set
Returns:None
wait_for_config_server_start(max_wait: int) → None

Waits for Config Server to start inside the Docker image

Parameters:max_wait – Seconds to wait for the application endpoint
Raises:RuntimeError – Raises runtime error if the config server does not start within max_wait
Returns:

VespaCloud

class vespa.deployment.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) → None

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: Optional[str] = None) → 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. Default to application name folder within user’s current working directory.
Returns:

a Vespa connection instance.

Vespa

class vespa.application.Vespa(url: str, port: Optional[int] = None, deployment_message: Optional[List[str]] = None, cert: Optional[str] = None, key: Optional[str] = None, output_file: IO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, application_package: Optional[vespa.package.ApplicationPackage] = None)
__init__(url: str, port: Optional[int] = None, deployment_message: Optional[List[str]] = None, cert: Optional[str] = None, key: Optional[str] = None, output_file: IO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, application_package: Optional[vespa.package.ApplicationPackage] = None) → None

Establish a connection with an existing 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 in case the ‘key’ parameter is none. If ‘key’ is not None, this should be the path of the certificate file.
  • key – Path to the key file.
  • output_file – Output file to write output messages.
  • application_package – Application package definition used to deploy the application.
>>> 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
application_package

Get application package definition, if available.

asyncio(connections: Optional[int] = 100, total_timeout: int = 10) → vespa.application.VespaAsync

Access Vespa asynchronous connection layer

Parameters:
  • connections – Number of allowed concurrent connections
  • total_timeout – Total timeout in secs.
Returns:

Instance of Vespa asynchronous layer.

delete_all_docs(content_cluster_name: str, schema: str, namespace: str = None) → requests.models.Response

Delete all documents associated with the schema

Parameters:
  • content_cluster_name – Name of content cluster to GET from, or visit.
  • schema – The schema that we are deleting data from.
  • namespace – The namespace that we are deleting data from. If no namespace is provided the schema is used.
Returns:

Response of the HTTP DELETE request.

delete_batch(batch: List[Dict], schema: Optional[str] = None, asynchronous=True, connections: Optional[int] = 100, total_timeout: int = 100, namespace: Optional[str] = None)

Delete a batch of data from a Vespa app.

Parameters:
  • batch – A list of dict containing the key ‘id’.
  • schema – The schema that we are deleting data from. The schema is optional in case it is possible to infer the schema from the application package.
  • asynchronous – Set True to get data in async mode. Default to True.
  • connections – Number of allowed concurrent connections, valid only if asynchronous=True.
  • total_timeout – Total timeout in secs for each of the concurrent requests when using asynchronous=True.
  • namespace – The namespace that we are deleting data from. If no namespace is provided the schema is used.
Returns:

List of HTTP POST responses

delete_data(schema: str, data_id: str, namespace: str = None) → vespa.io.VespaResponse

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.
  • namespace – The namespace that we are deleting data from. If no namespace is provided the schema is used.
Returns:

Response of the HTTP DELETE request.

feed_batch(batch: List[Dict], schema: Optional[str] = None, asynchronous=True, connections: Optional[int] = 100, total_timeout: int = 100, namespace: Optional[str] = None, batch_size=1000, output: bool = True)

Feed a batch of data to a Vespa app.

Parameters:
  • batch – A list of dict containing the keys ‘id’ and ‘fields’ to be used in the feed_data_point().
  • schema – The schema that we are sending data to. The schema is optional in case it is possible to infer the schema from the application package.
  • asynchronous – Set True to send data in async mode. Default to True.
  • connections – Number of allowed concurrent connections, valid only if asynchronous=True.
  • total_timeout – Total timeout in secs for each of the concurrent requests when using asynchronous=True.
  • namespace – The namespace that we are sending data to. If no namespace is provided the schema is used.
  • batch_size – The number of documents to feed per batch.
  • output – Prints a final message about the feed result.
Returns:

List of HTTP POST responses

feed_data_point(schema: str, data_id: str, fields: Dict, namespace: str = None) → vespa.io.VespaResponse

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.
  • namespace – The namespace that we are sending data to.
Returns:

Response of the HTTP POST request.

feed_df(df: pandas.core.frame.DataFrame, include_id: bool = True, id_field='id', **kwargs)

Feed data contained in a DataFrame.

Parameters:
  • df – A DataFrame containing a required ‘id’ column and the remaining fields to be fed.
  • include_id – Include id on the fields to be fed. Default to True.
  • id_field – Name of the column containing the id field.
  • kwargs – Additional parameters are passed to feed_batch().
Returns:

List of HTTP POST responses

get_application_status() → Optional[requests.models.Response]

Get application status.

Returns:
get_batch(batch: List[Dict], schema: Optional[str] = None, asynchronous=True, connections: Optional[int] = 100, total_timeout: int = 100, namespace: Optional[str] = None)

Get a batch of data from a Vespa app.

Parameters:
  • batch – A list of dict containing the key ‘id’.
  • schema – The schema that we are getting data from. The schema is optional in case it is possible to infer the schema from the application package.
  • asynchronous – Set True to get data in async mode. Default to True.
  • connections – Number of allowed concurrent connections, valid only if asynchronous=True.
  • total_timeout – Total timeout in secs for each of the concurrent requests when using asynchronous=True.
  • namespace – The namespace that we are getting data from. If no namespace is provided the schema is used.
Returns:

List of HTTP POST responses

get_data(schema: str, data_id: str, namespace: str = None) → vespa.io.VespaResponse

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.
  • namespace – The namespace that we are getting data from. If no namespace is provided the schema is used.
Returns:

Response of the HTTP GET request.

get_model_endpoint(model_id: Optional[str] = None) → Optional[requests.models.Response]

Get model evaluation endpoints.

get_model_from_application_package(model_name: str)

Get model definition from application package, if available.

predict(x, model_id, function_name='output_0')

Obtain a stateless model evaluation.

Parameters:
  • x – Input where the format depends on the task that the model is serving.
  • model_id – The id of the model used to serve the prediction.
  • function_name – The name of the output function to be evaluated.
Returns:

Model prediction.

query(body: Optional[Dict] = None) → vespa.io.VespaQueryResponse

Send a query request to the Vespa application.

Send ‘body’ containing all the request parameters.

Parameters:body – Dict containing all the request parameters.
Returns:The response from the Vespa application.
query_batch(body_batch: Optional[List[Dict]] = None, asynchronous=True, connections: Optional[int] = 100, total_timeout: int = 100, **kwargs)

Send queries in batch to a Vespa app.

Parameters:
  • body_batch – A list of dict containing all the request parameters. Set to None if using ‘query_batch’. of the field to use to recall and the second element is a list of the values to be recalled.
  • asynchronous – Set True to send data in async mode. Default to True.
  • connections – Number of allowed concurrent connections, valid only if asynchronous=True.
  • total_timeout – Total timeout in secs for each of the concurrent requests when using asynchronous=True.
  • kwargs – Additional parameters to be sent along the request.
Returns:

List of HTTP POST responses

update_batch(batch: List[Dict], schema: Optional[str] = None, asynchronous=True, connections: Optional[int] = 100, total_timeout: int = 100, namespace: Optional[str] = None)

Update a batch of data in a Vespa app.

Parameters:
  • batch – A list of dict containing the keys ‘id’, ‘fields’ and ‘create’ (create defaults to False).
  • schema – The schema that we are updating data to. The schema is optional in case it is possible to infer the schema from the application package.
  • asynchronous – Set True to update data in async mode. Default to True.
  • connections – Number of allowed concurrent connections, valid only if asynchronous=True.
  • total_timeout – Total timeout in secs for each of the concurrent requests when using asynchronous=True.
  • namespace – The namespace that we are updating data. If no namespace is provided the schema is used.
Returns:

List of HTTP POST responses

update_data(schema: str, data_id: str, fields: Dict, create: bool = False, namespace: str = None) → vespa.io.VespaResponse

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
  • namespace – The namespace that we are updating data. If no namespace is provided the schema is used.
Returns:

Response of the HTTP PUT request.

wait_for_application_up(max_wait: int) → None

Wait for application ready.

Parameters:max_wait – Seconds to wait for the application endpoint
Raises:RuntimeError – If the application did not start in the time given by the :max_wait: param.
Returns: