For the complete documentation index, see llms.txt. This page is also available as Markdown.

Vespa Cloud

Feed, update, delete and search documents in a Vespa Cloud application with a data-plane access token: YQL queries, keyword search and vector (nearest-neighbor) search.

Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

Connector
Authentication

Vespa Cloud

Access token

Vespa Cloud

Connect to a Vespa Cloud application with a data-plane access token to feed, update, delete and search documents.

Set up in Vespa Cloud

  1. Prepare the Vespa Cloud account or service that the workflow will access. Grant access to the required resources and operations.

  2. Token endpoint URL: The endpoint marked 'Token' on your application's Endpoints tab in the Vespa Cloud console, e.g. https://abc123.def456.z.vespa-app.cloud. Do NOT paste the mTLS endpoint: a bearer token is rejected there at the TLS layer before Vespa Cloud ever reads the request.

  3. Access token: A data-plane token from the Vespa Cloud console (Account > Tokens). The token id must be listed under the application's in services.xml with the 'read' and/or 'write' permission this connection's actions need.

Set up in StackAI

  1. Open Settings → Connections, add a connection, and select Vespa Cloud.

  2. Enter the credentials and connection details in the fields below.

  3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

Connection fields

StackAI field
Required
What to enter

Token endpoint URL

Yes

The endpoint marked 'Token' on your application's Endpoints tab in the Vespa Cloud console, e.g. https://abc123.def456.z.vespa-app.cloud. Do NOT paste the mTLS endpoint: a bearer token is rejected there at the TLS layer before Vespa Cloud ever reads the request. Provider instructions.

Access token

Yes

A data-plane token from the Vespa Cloud console (Account > Tokens). The token id must be listed under the application's <clients><client permissions=...><token id=...> in services.xml with the 'read' and/or 'write' permission this connection's actions need. Provider instructions.

Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

Use an action

  1. Add the required Vespa Cloud action to the workflow.

  2. Select a connection when the action requests one.

  3. Complete the required fields. Use the reference picker when a value comes from another workflow step.

  4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

Actions

Feed Document

Create a document, or replace it entirely if the id already exists.

Required permissions: write.

Inputs

Field
Type
Required
Description

Namespace

string

Yes

The namespace the document lives in. Set by whoever feeds the data; often the same as the document type or 'default'.

Document type

string

Yes

The schema (document type) of the document, as declared in your Vespa application.

Document ID

string

Yes

The user-defined id of the document (the part after '::' in a full Vespa id).

Document fields (JSON)

textarea

Yes

The document content as a JSON object. Keys must be field names from the schema.

Show advanced fields

boolean

No

Reveal the test-and-set condition. Default: false.

Only if condition holds

string

No

Optional test-and-set condition. The write only happens when this document-selection expression is true for the stored document.

Outputs

Field
Type
Description

Document ID

string

Full id of the document that was written.

Path

string

Document API path the operation ran against.

Get Document

Fetch one document by its id.

Required permissions: read.

Inputs

Field
Type
Required
Description

Namespace

string

Yes

The namespace the document lives in. Set by whoever feeds the data; often the same as the document type or 'default'.

Document type

string

Yes

The schema (document type) of the document, as declared in your Vespa application.

Document ID

string

Yes

The user-defined id of the document (the part after '::' in a full Vespa id).

Show advanced fields

boolean

No

Reveal the fields-to-return and content cluster options. Default: false.

Fields to return

string

No

Which fields to include. Leave empty for all document fields, or list them as <type>:<field1>,<field2>.

Content cluster

string

No

Name of the content cluster (from services.xml). Only needed when the application has more than one content cluster.

Outputs

Field
Type
Description

Found

boolean

Whether a document with that id exists.

Document ID

string

Full id of the requested document.

Fields

dict

The document's fields as a JSON object (empty when not found).

Update Document

Change some fields of an existing document without touching the rest.

Required permissions: write.

Inputs

Field
Type
Required
Description

Namespace

string

Yes

The namespace the document lives in. Set by whoever feeds the data; often the same as the document type or 'default'.

Document type

string

Yes

The schema (document type) of the document, as declared in your Vespa application.

Document ID

string

Yes

The user-defined id of the document (the part after '::' in a full Vespa id).

Fields to set (JSON)

textarea

No

Fields and their new values. Each listed field is overwritten; unlisted fields keep their values.

Show advanced fields

boolean

No

Reveal add/remove operations and the test-and-set condition. Default: false.

Values to add (JSON)

textarea

No

For array, weighted set or map fields: values to append to what is already stored.

Values to remove (JSON)

textarea

No

For array, weighted set or map fields: values to delete from what is stored.

Create if missing

boolean

No

Create the document (with only the given fields) when no document has this id. Default: false.

Only if condition holds

string

No

Optional test-and-set condition. The write only happens when this document-selection expression is true for the stored document.

Outputs

Field
Type
Description

Document ID

string

Full id of the document that was written.

Path

string

Document API path the operation ran against.

Delete Document

Permanently remove a document by its id.

Required permissions: write.

Inputs

Field
Type
Required
Description

Namespace

string

Yes

The namespace the document lives in. Set by whoever feeds the data; often the same as the document type or 'default'.

Document type

string

Yes

The schema (document type) of the document, as declared in your Vespa application.

Document ID

string

Yes

The user-defined id of the document (the part after '::' in a full Vespa id).

Show advanced fields

boolean

No

Reveal the test-and-set condition. Default: false.

Only if condition holds

string

No

Optional test-and-set condition. The delete only happens when this document-selection expression is true for the stored document.

Outputs

Field
Type
Description

Document ID

string

Full id of the document that was removed.

Path

string

Document API path the operation ran against.

Query Documents (YQL)

Run any YQL query against your application and get the matching documents.

Required permissions: read.

Inputs

Field
Type
Required
Description

YQL query

textarea

Yes

The query in Vespa's YQL language.

Search text

string

No

Free text used where the YQL says userQuery().

Max hits

integer

No

How many documents to return. Minimum: 0. Maximum: 400. Default: 10.

Offset

integer

No

Number of hits to skip, for paging. Minimum: 0. Default: 0.

Ranking profile

string

No

Rank profile from your schema to score hits with. Leave empty for the schema's default profile.

Show advanced fields

boolean

No

Reveal query tensors, the document summary and the timeout. Default: false.

Query inputs (JSON)

textarea

No

Values for rank-profile inputs such as query tensors, keyed by input name.

Document summary

string

No

Which document summary class to return fields from. Leave empty for the default summary.

Timeout (ms)

integer

No

How long Vespa may spend on the query before returning partial results. Minimum: 1. Default: 5000.

Outputs

Field
Type
Description

Hits

object_array

Matching documents, best first.

Total matches

integer

Total number of documents that matched, not just the ones returned.

Coverage %

number

Percentage of the corpus that was searched; below 100 means the query timed out or nodes were down.

Next offset

integer

Offset to pass on the next call to get the following page. Empty when there are no more hits.

Search Documents

Keyword search over a document type using plain text.

Required permissions: read.

Inputs

Field
Type
Required
Description

Document type

string

Yes

The schema to search in.

Search text

string

Yes

What to search for, as a person would type it.

Max hits

integer

No

How many documents to return. Minimum: 0. Maximum: 400. Default: 10.

Show advanced fields

boolean

No

Reveal paging, ranking and timeout options. Default: false.

Offset

integer

No

Number of hits to skip, for paging. Minimum: 0. Default: 0.

Ranking profile

string

No

Rank profile from your schema to score hits with. Leave empty for the schema's default profile.

Field to search

string

No

Which field the words are matched against. Leave empty for the schema's default fieldset.

Document summary

string

No

Which document summary class to return fields from. Leave empty for the default summary.

Timeout (ms)

integer

No

How long Vespa may spend on the query before returning partial results. Minimum: 1. Default: 5000.

Outputs

Field
Type
Description

Hits

object_array

Matching documents, best first.

Total matches

integer

Total number of documents that matched, not just the ones returned.

Coverage %

number

Percentage of the corpus that was searched; below 100 means the query timed out or nodes were down.

Next offset

integer

Offset to pass on the next call to get the following page. Empty when there are no more hits.

Find Similar Documents

Vector (nearest-neighbor) search: find the documents whose embedding is closest to a vector you provide.

Required permissions: read.

Inputs

Field
Type
Required
Description

Document type

string

Yes

The schema that holds the embedding field.

Embedding field

string

Yes

The tensor field in the schema that stores document embeddings.

Query vector

textarea

Yes

The embedding to compare against, as a list of numbers.

Ranking profile

string

Yes

Rank profile that declares the query tensor and scores by closeness.

Max hits

integer

No

How many documents to return. Minimum: 0. Maximum: 400. Default: 10.

Show advanced fields

boolean

No

Reveal query tensor name, target hits, filter, exact search, summary and timeout options. Default: false.

Query tensor name

string

No

Name of the query tensor input in the rank profile. Usually 'q'. Default: q.

Target hits

integer

No

How many nearest neighbors the index should retrieve before ranking. Higher is more accurate but slower. Minimum: 1. Default: 100.

Filter (YQL)

string

No

Optional extra condition to restrict candidates, in YQL.

Exact search

boolean

No

Compute exact distances instead of using the approximate index. Slower but precise. Default: false.

Document summary

string

No

Which document summary class to return fields from. Leave empty for the default summary.

Timeout (ms)

integer

No

How long Vespa may spend on the query before returning partial results. Minimum: 1. Default: 5000.

Outputs

Field
Type
Description

Hits

object_array

Matching documents, best first.

Total matches

integer

Total number of documents that matched, not just the ones returned.

Coverage %

number

Percentage of the corpus that was searched; below 100 means the query timed out or nodes were down.

List Documents

Page through all documents of a type, optionally filtered or limited to recently modified ones.

Required permissions: read.

Inputs

Field
Type
Required
Description

Namespace

string

Yes

The namespace the document lives in. Set by whoever feeds the data; often the same as the document type or 'default'.

Document type

string

Yes

The schema (document type) of the document, as declared in your Vespa application.

Max documents

integer

No

Roughly how many documents to return in this call. Minimum: 1. Maximum: 1000. Default: 100.

Show advanced fields

boolean

No

Reveal the time filter, selection filter, field set, cluster and continuation token. Default: false.

Modified after

datetime

No

Only return documents changed at or after this time.

Filter (document selection)

string

No

Only return documents matching this expression.

Fields to return

string

No

Which fields to include. Leave empty for all document fields, or list them as <type>:<field1>,<field2>.

Content cluster

string

No

Name of the content cluster (from services.xml). Only needed when the application has more than one content cluster.

Continuation token

string

No

Token from a previous call to continue where it stopped.

Outputs

Field
Type
Description

Documents

object_array

The documents returned in this batch.

Count

integer

How many documents this batch contains.

Continuation token

string

Pass into the next call to keep going. Empty when done.

Triggers

A trigger starts a workflow when its configured event occurs. Configure the event and filters before enabling the trigger.

Document Created or Updated

Starts the workflow for each document that was added or modified in a document type since the last check.

The connection's access token needs 'read' permission. Content cluster is only needed for applications with more than one content cluster; leave the advanced fields empty otherwise.

Required permissions: read.

Configuration

Field
Type
Required
Description

Namespace

string

Yes

The namespace the document lives in. Set by whoever feeds the data; often the same as the document type or 'default'.

Document type

string

Yes

The schema (document type) of the document, as declared in your Vespa application.

Show advanced fields

boolean

No

Reveal the filter, fields-to-return and content cluster options. Default: false.

Filter (document selection)

string

No

Only fire for documents matching this expression.

Fields to return

string

No

Which fields to include. Leave empty for all document fields, or list them as <type>:<field1>,<field2>.

Content cluster

string

No

Name of the content cluster (from services.xml). Only needed when the application has more than one content cluster.

Event inputs

Field
Type
Required
Description

Document ID

string

Yes

Full id of the changed document. Default: .

Namespace

string

Yes

Namespace of the document. Default: .

Document type

string

Yes

Schema of the document. Default: .

User-defined ID

string

Yes

The id part after '::'. Default: .

Fields

object

Yes

The document's current fields.

Outputs

Field
Type
Description

Document ID

string

Full id of the changed document.

Namespace

string

Namespace of the document.

Document type

string

Schema of the document.

User-defined ID

string

The id part after '::'.

Fields

dict

The document's current fields.

Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.

Last updated

Was this helpful?