• [+] expand all

Schema inheritance

Both document types and full schemas can be inherited to make it easy to design a structured application package with little duplication. Document type inheritance defines a type hierarchy which is also useful for applications that federate queries as queries can be written to the common supertype. This guide covers the different elements in the schema that supports inheritance:

  1. Schemas
  2. Document types
  3. Rank profiles
  4. Document summaries

Note: Inheritance is not to confuse with parent/child, which is a feature to import field values at query time.

Schema inheritance

A schema that inherits another gets all the content of the parent schema as if it was defined inside the inheriting schema. A schema that inherits another must also (explicitly) inherit its document type.

Document type inheritance

Both schemas music and books have the title field through inheritance:

schema items {
    document items {
        field title type string {
            indexing: summary | index
        }
    }
}

schema books {
    document books inherits items {
        field author type string {
            indexing: summary | index
        }
    }
}

schema music {
    document music inherits items {
        field artist type string {
            indexing: summary | index
        }
    }
}

This is equivalent to:

schema books {
    document books {
        field title type string {
            indexing: summary | index
        }
        field author type string {
            indexing: summary | index
        }
    }
}

schema music {
    document music  {
        field title type string {
            indexing: summary | index
        }
        field artist type string {
            indexing: summary | index
        }
    }
}

Notes:

  • Multiple inheritance and multiple levels of inheritance is supported.
  • Inheriting a document type defined in another content cluster is allowed.
  • Overriding fields defined in supertypes is not allowed.
  • Imported fields defined in supertypes are not inherited.

Rank profile inheritance

Where fields define the document types, rank profiles define the computations over the documents. Rank profiles can be inherited:

schema items {
    rank-profile items_ranking_base {
        function title_score() {
            expression: fieldLength(title)
        }
        first-phase {
            expression: title_score
        }
        summary-features {
            title_score
        }
    }
}

schema books {
    rank-profile items_ranking inherits items_ranking_base {}

    rank-profile items_subschema_ranking inherits items_ranking_base {
        first-phase {
            expression: title_score + fieldMatch(author)
        }
        summary-features inherits items_ranking_base {
            fieldMatch(author)
        }
    }
}

schema music {
    rank-profile items_ranking inherits items_ranking_base {}

    rank-profile items_subschema_ranking inherits items_ranking_base {
        first-phase {
            expression: title_score + fieldMatch(artist)
        }
        summary-features inherits items_ranking_base {
            fieldMatch(artist)
        }
    }
}

items_ranking can be considered the "base" ranking. Pro tip: Set this as the default ranking profile by modifying the default query profile:

<query-profile id="default">
    <field name="ranking.profile">items_ranking</field>
</query-profile>

Queries using ranking.profile=default will then use the first-phase ranking defined in items.sd.

Another way to inherit behavior is to override the first-phase ranking in the sub-schemas, still using functions defined in the super-schema (e.g. title_score).

Summary features are rank features computed during ranking, to be included in result summaries. Summary features can be inherited - the above will include scores from features in super- and sub-schema - example result:

    "summaryfeatures": {
        "fieldMatch(author)": 0,
        "rankingExpression(title_score)": 4
    }

Here, both books and music schemas implement rank profiles with same names (e.g. items_subschema_ranking), so they can be used in queries spanning both. If a query's rank profile can not be found in a given schema, Vespa's default rank profile nativerank is used.

Document summary inheritance

Document summaries can inherit others defined in the same or an inherited schema.

schema books {
    document-summary items_summary_tiny {
        summary title type string {
            source: title
        }
    }

    document-summary items_summary_full inherits items_summary_tiny {
        summary author type string {
            source: author
        }
    }
}