English for Vespa Search Engine

Vespa conversations combine search-engine vocabulary shared with tools like Elasticsearch (schema, index) with ranking-specific terms that are more unusual — tensor field, first-phase ranking — and blurring these two categories makes it harder to explain whether a relevance issue is a data problem or a scoring problem.

Key Vocabulary

Document schema — the definition of a document type’s fields, their types, and how each field is indexed, matched, and made available for ranking, declared in Vespa’s schema language. “That field isn’t showing up in search results because it’s defined as attribute only in the schema, not index — it’s not being tokenized for text matching.”

Ranking profile — a named configuration of how documents are scored for a given query, combining features like text match, freshness, and popularity into a single relevance score. “We added a new ranking profile for the mobile app that weights recency more heavily than the default web ranking profile does.”

Tensor field — a multi-dimensional numeric field type used to store embeddings or other structured numeric data, enabling operations like dot-product similarity directly inside ranking expressions. “Store the embedding as a tensor field so we can compute cosine similarity against the query vector natively during ranking, instead of in a separate service.”

Content cluster — the group of nodes responsible for storing and serving a set of document types, configurable independently of the container cluster that handles query processing. “We’re scaling the content cluster separately from the container cluster since storage growth and query load aren’t growing at the same rate.”

First-phase vs. second-phase ranking — a two-stage scoring approach where a cheap first-phase function ranks all matching documents, and a more expensive second-phase function re-ranks only the top candidates. “Move that expensive feature computation into second-phase ranking — running it on every matching document in first-phase is what’s driving up query latency.”

Common Phrases

• “Is this field indexed for text search, or is it just an attribute we’re filtering on?”
• “Which ranking profile is this query actually using — the default, or a custom one?”
• “Should this embedding be a tensor field so we can rank on it directly?”
• “Is the content cluster or the container cluster the bottleneck under this load?”
• “Could we move this expensive feature to second-phase ranking instead of running it on every candidate?”

Example Sentences

Debugging a relevance complaint: “Results looked off because the query was hitting the default ranking profile instead of the custom one that weights our business-priority signal — we hadn’t wired the new profile into that endpoint yet.”

Explaining a latency fix: “We cut p99 latency by moving the tensor similarity computation from first-phase to second-phase ranking, since first-phase only needs a cheap approximate score to narrow the candidate set.”

Discussing a scaling decision: “We scaled the content cluster independently of the container cluster this quarter — storage was growing fast from new document types, but query volume was flat.”

Professional Tips

• Distinguish document schema field types (index vs attribute) explicitly when debugging a missing search result — it’s one of the most common sources of “why isn’t this showing up” confusion.
• Name the specific ranking profile in use when discussing a relevance issue — “search results are bad” is far less actionable than “the mobile ranking profile is underweighting recency.”
• Use tensor field precisely for embedding or structured numeric data, not as a synonym for any numeric field — it signals the field supports vector operations in ranking expressions.
• Reference first-phase and second-phase ranking by name when proposing a latency fix — it shows you understand Vespa’s specific two-stage scoring model, not just “make ranking faster.”

Practice Exercise

1. Explain the difference between an index field and an attribute field in one sentence.
2. Describe what a ranking profile controls and why a query might need more than one.
3. Write a sentence explaining why first-phase and second-phase ranking exist as separate stages.

Beyond the Basics: Refining Your Professional Communication with Vespa

The core vocabulary of Vespa – schema definitions, ranking profiles, tensor fields, and content clusters – is a crucial foundation. But simply knowing what these things are isn’t enough; mastering how to discuss them effectively in a professional setting is key for developers working on complex search projects. This section focuses specifically on the nuances of phrasing used in code reviews, Slack conversations, and pull request descriptions when dealing with Vespa’s powerful features. It’s about moving beyond simple definitions and demonstrating a sophisticated understanding of how these components contribute to a robust search solution.

One common pitfall for non-native speakers is over-formal language or using jargon excessively without context. While precision is important, overly complex sentences can be difficult to parse quickly. Similarly, constantly throwing around technical terms without explaining why they’re relevant can alienate colleagues. Think about your audience – your team members are likely experts in search technology, but they might not always appreciate a verbose explanation of the underlying mathematics behind tensor fields if you’re simply suggesting a slight adjustment to a ranking profile. Instead, focus on clear, concise communication that highlights the impact of your changes. For example, instead of saying “The vector field’s divergence is exceeding acceptable thresholds,” consider “We need to refine the ranking profile to reduce the influence of this feature, as it’s currently over-emphasizing [specific term].” This approach immediately communicates the issue and suggests a tangible solution. Furthermore, active voice is almost always preferable – “I adjusted the weighting” is clearer than “The weighting was adjusted by me.”

Another area where communication can be improved is in pull request descriptions. A good PR description doesn’t just state what you changed; it explains why. Developers reviewing your code need to understand the reasoning behind your decisions, allowing them to quickly assess the validity of your changes and provide targeted feedback. Don’t assume they automatically know why you chose a particular ranking profile or adjusted a tensor field. Provide context – briefly outlining the problem you were trying to solve and how this change addresses it. A well-structured PR description demonstrates professionalism, facilitates collaboration, and ultimately speeds up the review process.

Finally, remember that constructive criticism is often best delivered with empathy. Frame feedback in terms of desired outcomes rather than pointing out flaws. Instead of saying “This query isn’t performing well,” try “Let’s explore ways to improve the ranking profile for this specific query type.” A little tact can go a long way in fostering a positive and productive team environment.

# Vespa - Querying with Filters

This command demonstrates filtering results based on multiple criteria using Vespa's powerful filter syntax. The `query` command accepts a JSON payload containing the desired filters.  The example below searches for documents that contain both "python" AND "programming" within their content, and also have a score greater than 0.8.

```json
{
  "query": {
    "filter": [
      {
        "match": {
          "content": "python programming"
        }
      },
      {
        "range": {
          "score": {
            "_gte": 0.8
          }
        }
      }
    ]
  }
}