Property Projections
Configure how model properties appear in persistence, search, API, and custom downstream contexts using opt-in projections.
Projections define how a model property appears in different downstream contexts. Each property on a model entity supports four projection types: persistence, search, API, and custom. Every projection is opt-in, meaning its absence indicates that the property is not included in that context.
Projection Types Overview
The four projection types serve distinct purposes in the data pipeline.
Projection Comparison
The following table summarises the configuration options available on each projection type.
| Projection | Key Fields | Use Case |
|---|---|---|
| Persistence | included, columnName | Map properties to database columns or document fields |
| Search | included, searchBehaviours, analyzer, boost, fieldName, dimensions, vectorSearchProfile | Configure search engine indexing and query behaviour |
| API | included, fieldName, readOnly | Control API request and response field exposure |
| Custom | included, metadata | Attach arbitrary key-value pairs for bespoke consumers |
Persistence Projection
The persistence projection controls how a property maps to the underlying data store. It has two configuration options.
| Property | Type | Description |
|---|---|---|
| included | boolean | Whether the property is included in the persistence layer |
| columnName | string (optional) | Override the column or field name in the target store; defaults to the property name if omitted |
{
"persistence": {
"included": true,
"columnName": "customer_email"
}
}Search Projection
The search projection is the most detailed projection type. It controls how a property is indexed, queried, and ranked by the search engine.
Core Settings
| Property | Type | Description |
|---|---|---|
| included | boolean | Whether the property is included in the search index |
| fieldName | string (optional) | Override the field name in the search index |
| key | boolean (optional) | Mark this field as the document key |
| boost | number (optional) | Relevance boost factor for scoring |
| analyzer | string (optional) | Analyser applied to both indexing and querying |
| indexAnalyzer | string (optional) | Analyser applied during indexing only |
| searchAnalyzer | string (optional) | Analyser applied during querying only |
| normalizer | string (optional) | Normaliser for keyword-style fields |
| synonymMap | string (optional) | Synonym map reference for query expansion |
Search Behaviours
Five boolean flags control how the field participates in search operations.
| Behaviour | Description |
|---|---|
| searchable | The field is included in full-text search queries |
| filterable | The field supports exact-match and range filter expressions |
| sortable | Results may be ordered by this field |
| facetable | The field produces facet counts for category navigation |
| retrievable | The field value is returned in search results |
Search Field Types
The search projection supports a comprehensive set of field types across several categories.
Vector Search Configuration
Properties with a vector search field type require additional configuration for similarity search.
| Property | Type | Description |
|---|---|---|
| dimensions | number | The number of dimensions in the vector (required for dense_vector) |
| vectorSearchProfile | string (optional) | Reference to a vector search profile defining the algorithm and parameters |
| similarityMetric | string (optional) | Distance function: cosine, dot_product, or l2_norm |
{
"search": {
"included": true,
"searchFieldType": "dense_vector",
"dimensions": 1536,
"vectorSearchProfile": "hnsw-default",
"similarityMetric": "cosine",
"searchBehaviours": {
"searchable": true,
"filterable": false,
"sortable": false,
"facetable": false,
"retrievable": true
}
}
}Profile Overrides and Sub-fields
Search projections support two advanced features for multi-profile and multi-field scenarios.
| Feature | Description |
|---|---|
| profileOverrides | Per-profile overrides keyed by search profile ID; each override replaces the default analyser, boost, or behaviours for that specific profile |
| Sub-field configuration | Multi-field mappings that index the same source property under different field types or analysers (for example, a text field with an additional keyword sub-field for exact matching) |
API Projection
The API projection determines how a property is exposed through generated API contracts.
| Property | Type | Description |
|---|---|---|
| included | boolean | Whether the property appears in API request and response payloads |
| fieldName | string (optional) | Override the field name in the API contract |
| readOnly | boolean (optional) | Mark the field as read-only (excluded from request bodies, included in responses) |
{
"api": {
"included": true,
"fieldName": "email",
"readOnly": false
}
}Custom Projection
The custom projection provides a flexible extension point for downstream systems not covered by the built-in projection types.
| Property | Type | Description |
|---|---|---|
| included | boolean | Whether the property is included for this custom consumer |
| metadata | Record<string, any> | Arbitrary key-value pairs consumed by external tooling or pipelines |
{
"custom": {
"included": true,
"metadata": {
"exportFormat": "parquet",
"piiClassification": "confidential",
"retentionDays": 365
}
}
}