overview.html

---
# Copyright Vespa.ai. All rights reserved.
title: "Vespa Overview"
redirect_from:
- /en/overview.html
---

<p>Vespa is a platform for applications which need low-latency computation over large data sets.
It stores and indexes your structured, text and vector data so that queries, selection and processing
and machine-learned model inference over the data can be performed quickly at serving time at any scale.
Functionality can be customized and extended with application components hosted within Vespa.
This document is an overview of the features and main components of Vespa.</p>


<h2 id="introduction">Introduction</h2>

<p>Vespa allows application developers to create applications that scale
to large amounts of data and high loads without sacrificing latency or reliability.
A Vespa application consists of a number of <em>stateless Java container clusters</em>
and zero or more <em>content</em> clusters storing data.</p>

<img src="/assets/img/vespa-overview.svg" width="825px" height="auto" alt="Vespa Overview" />

<p>The <a href="../applications/containers.html">stateless <strong>container</strong> clusters</a> host components
which process incoming data and/or queries and their responses.
These components provide functionality belonging to the platform like indexing
transformations and the global stages of query execution, but can also include the middleware logic of the application.
Application developers can configure their Vespa system with a single stateless cluster which
performs all such functions, or create different clusters for each kind of task.
The container clusters then pass queries and data operations on to the appropriate nodes in the content clusters.
If the application uses data it does not own, you can add components to access data from external services as well.</p>

<p><a href="../content/elasticity.html"><strong>Content</strong> clusters</a> in Vespa are responsible for storing data
and execute queries and inferences over the data.
Queries can range from simple data lookups for content serving to complex conditions for selecting the relevant
data, ranking it using machine-learned models, and grouping and aggregating the data across all nodes
participating in the query.
All the operations provided by Vespa scales to more content, more expensive inference, and higher query volume
simply by adding more nodes to the content clusters.</p>

<p>When changing the nodes of a content cluster for scaling or on node failure,
content clusters automatically re-balance data in the background
to maintain a balanced distribution at the configured redundancy level.
Faulty nodes are also automatically removed from the serving path to avoid any impact to queries and
writes (failover).</p>

<p>After intermediate processing in a container cluster, data is written to content clusters.
Writes are persistent and visible in all queries after receiving an ack on the write message,
after a few milliseconds. Each write is guaranteed to either succeed or provide failure information
response within a given time limit, and writes and scale linearly with the available resources, indefinitely.
In addition to rewriting and removing entire documents, writes may selectively modify only individual document fields.
Writes can be sent directly over HTTP/2, or by using a Java client &mdash;
refer to the <a href="../reference/api/api.html">API documentation</a>.</p>

<p>Each document instance stored in Vespa are of a type defined in a configured <a href="../basics/schemas.html">schema</a>,
which defines the document fields and how to store and index them, as well as the ranking and inference
profiles that belongs to the document type. Applications can contain any number of schemas for different
data types, and configure them to be stored either in the same or multiple content clusters.</p>

<p>Container and content clusters handle all the end user traffic of a Vespa application,
but there's also a third type of cluster, the <em>admin and config clusters</em>.
These set up and manage the other clusters in the application according to configuration, and
manages the process of changing the clusters safely without disruption to traffic
when the configuration changed.</p>

<p>A Vespa application is completely specified by an
<a href="../basics/applications.html"><em>application package</em></a>,
which is a directory structure containing a declaration of the clusters to run as part of the application,
the content schemas, any machine-learned models and Java components,
and other configuration or data files needed by various features.
Application developers create a running application from their application package by
<em>deploying</em> it to any node in the config cluster.
Changes to a running application is made in the same way: By changing the application package and deploying again.
Once Vespa is installed and started on a node,
it is managed by the config system such that the entire system can be treated as a single unit,
and application owners do not need to perform any administration tasks locally on the nodes running the application.
It is also possible to configure nodes as <em>log servers</em> on Vespa. These will collect logs in real time
from all the nodes of the application. By default, the first node in the config server cluster performs this role.</p>

<p>The rest of this document provides some more detail on the functions Vespa performs.</p>


<h2 id="vespa-operations">Vespa operations</h2>

<p>Vespa accepts the following operations:</p>

<ul>
	<li>Writes: Put (add and replace) and remove documents, and update fields in these.</li>
	<li>Lookup of a document (or some subset of it) by id.</li>
	<li><a href="../querying/query-api.html">Queries</a>:
    <a href="../querying/query-language.html"><em>Select</em></a> documents
    whose fields match conditions, which search
    free-text fields, structured data or <a href="../querying/nearest-neighbor-search">vector spaces (ANN)</a>.
    Any number of such conditions can be combined freely in boolean trees to
    define the full query to be executed.
    Vespa will compute a query plan over the conditions which executes them
    efficiently with any number of conditions such as e.g. filters combined with ANN conditions.
    Matches to a query can be passed through an inference step which can compute
    any business logic or machine-learned model expressed as a
    <a href="../reference/ranking/ranking-expressions.html">ranking expression</a> or <a href="../ranking/onnx">ONNX model</a>.
    Optionally, the highest scoring matches can also run through a second stage of this,
    to spend more computational resources on promising candidates.
    The final documents are ordered according to their score from these inferences (<a href="../basics/ranking.html"><em>ranking</em></a>),
    or by explicit <a href="../reference/querying/sorting-language.html"><em>sorting</em></a>.
    Matches to queries can be <a href="../querying/grouping.html"><em>grouped</em></a>
    hierarchically by field values,
    where each group can contain aggregated values over the data in the group
    This can be used to calculate values for, e.g., navigation aids, tag clouds,
    graphs or for clustering in a distributed fashion
    without having to transfer the distributed to a single container node.</li>
	<li>Data dumps: Content matching some criterion can be streamed out for background reprocessing,
    backup, etc., by using the <a href="../writing/visiting.html"><em>visit</em></a> operation.</li>
	<li><a href="../reference/applications/components.html">Any other custom network request</a>
    which can be handled by application components deployed on a container cluster.</li>
</ul>


<h2 id="the-stateless-container">The stateless container</h2>

<p><a href="../applications/containers.html">Container clusters</a> host the application components
which employ the operations listed above and process their return data.
Vespa provides a set of components out of the box, together with component infrastructure:
dependency injection,
with added support for injection of config from the admin server or the application package;
a component model based on OSGi;
a shared mechanism to chain components into handler chains for modularity
as well as metrics and logging.
The container also provides the network layer for handling and issuing remote requests -
HTTP is provided out of the box,
and other protocols/transports can be transparently plugged in as components.</p>

<p>Developers can make changes to components (and of course their configuration)
simply by redeploying their application package -
the system takes care of copying the components to the nodes of the cluster
and loading/unloading components impacting request serving or restarting nodes.</p>



<h2 id="content_clusters">Content clusters</h2>

<p><a href="../content/elasticity.html">Content clusters</a> store data
and maintain distributed indices of data for searches and selects.
Data is replicated over multiple nodes, with a number of copies specified by the application,
such that the cluster can automatically repair itself on loss of a node or a disk.
Using the same mechanism, clusters can also be grown or shrunk while online,
simply by changing the set of available nodes declared in the application package.</p>

<p>Lookup of an individual document is routed directly to a node storing that document,
while queries are spread over a subset of nodes which contain the queried documents.
Complex queries are performed as distributed algorithms with multiple steps back and
forth between the container and the content nodes; this is to achieve the low latency
which is one of the main design goals of Vespa.</p>



<h2 id="administration_and_developer_support">Administration clusters and developer support</h2>

<p>The <a href="../basics/applications.html">single configuration cluster</a>
controls all the other clusters of the system.

A config server derives the low level configuration of each individual cluster, node and process,
such that the application developer can specify the desired system on a higher level
without worrying about its detailed realization.
Whenever the application package is redeployed,
the system will compute the necessary changes in configuration and manage the process
of moving safely from the current to the new configuration without disrupting queries or writes.</p>

Other admin clusters in Vespa are the cluster controller cluster (controls one or more content clusters),
logserver cluster (logserver holds log archive for logs from all nodes in the application)
and service location brokers (slobroks, which are a name service used by some services in Vespa).

<h3 id="application_packages">Application packages</h3>
<p>Application packages may be <a href="../reference/api/deploy-v2.html">changed, redeployed</a>
and <a href="../reference/api/config-v2.html">inspected</a> over an HTTP REST API,
or through a <a href="../clients/vespa-cli.html#deployment">command line interface</a>.
The administration cluster runs over <a href="https://zookeeper.apache.org">ZooKeeper</a>
to make changes to configuration singular and consistent, and to avoid having a single point of failure.</p>

<p>An application package looks the same, and is deployed the same way,
whether it specifies a large system with hundreds of nodes or a single node running all services.
The only change needed is to the lists of nodes making up the cluster.
The container clusters may also be started within a single Java VM by "deploying" the
application package from a method call.
This is useful for testing applications in an IDE and in unit tests.
Application packages with components can be <a href="../applications/developer-guide.html">developed</a>
in an IDE using Maven starting from sample applications.</p>



<h2 id="summary">Summary</h2>

<p>Vespa allows functionally rich and highly available applications to be developed to scale and perform to
high standards without burdening developers with the considerable low level complexity this requires.
It allows developers to evolve and grow their applications over time without taking the system offline,
and lets them avoid complex data and page precomputing schemes
which lead to stale data that cannot be personalized,
since this often requires complex queries to complete in real user time
over data which is constantly changing at the same time.</p>

<p>For more details, read <a href="features.html">Vespa Features</a>, or try to
<a href="../basics/deploy-an-application.html">deploy an application</a>.</p>