Indexing conventions

27 min

Note Indexing conventions require CMS 13 version 13.1.0 or later.

Configure indexing conventions to customize how content types are indexed to Optimizely Graph. Use the configureConventions parameter in AddContentGraph during application startup.

Conventions apply only to content that the SearchIndexer role can read. Optimizely Graph does not index content without SearchIndexer read access, regardless of convention settings. CMS does not add the SearchIndexer role to custom access rights. If you clear Inherit settings from parent item on a content item, give the SearchIndexer role read access. See Verify SearchIndexer access rights.

services.AddContentGraph(configureConventions: conventions =>
{
    conventions.ForInstancesOf<ProductPage>()
        .IncludeField(p => p.TotalPrice())
        .IncludeField(p => p.ComputedTitle(), IndexingType.Searchable);

    conventions.ExcludeContentType<InternalPage>();
});

Note Content types and content data are not resynced automatically when conventions change and the site restarts. After changing conventions in code and redeploying the site, re-run the Optimizely Graph Full Synchronization job so data is consistent with your configurations. Not doing so results in unpredictable outcomes.

Exclude content types

Exclude content types from syncing to the Optimizely Graph schema. Optimizely Graph does not index content of excluded content types.

The following example excludes InternalPage and DraftBlock:

conventions.ExcludeContentType<InternalPage>()
    .ExcludeContentType<DraftBlock>();

When excluded, InternalPage and DraftBlock are removed from the GraphQL schema, and their content is not synced to Optimizely Graph.

When you add content of excluded content types to a ContentArea or ContentAreaItem property of another type, those items are not included in the indexed content area.

Computed fields

Indexing conventions let you add computed fields to content types at indexing time without modifying the content model itself. Computed fields are methods whose return values are indexed alongside regular CMS properties.

Note Define computed fields as extension methods rather than instance methods on the content type. This keeps the content model clean and separates indexing logic from the domain model. Extension methods are the recommended approach for computed fields.

Define computed fields

Define computed fields as extension methods in a separate static class. This keeps indexing logic separate from the content model.

The following example uses a page type called ProductPage:

[ContentType]
public class ProductPage : PageData
{
    public virtual string ProductName { get; set; }
    public virtual int Quantity { get; set; }
    public virtual double Price { get; set; }
}

Define the computed field as an extension method:

public static class ProductPageComputedFields
{
    public static double TotalPrice(this ProductPage page)
    {
        return page.Quantity * page.Price;
    }
}

conventions.ForInstancesOf<ProductPage>()
    .IncludeField(p => p.TotalPrice());

After ProductPage syncs to Optimizely Graph, query TotalPrice using the following:

{
  ProductPage {
    items {
      ProductName
      Quantity
      Price
      TotalPrice
    }
  }
}

Specify the indexing type for the computed field as the second parameter of IncludeField:

conventions.ForInstancesOf<ProductPage>()
    .IncludeField(p => p.TotalPrice(), IndexingType.Queryable);

Computed fields with service injection

Computed fields can accept an IServiceProvider parameter for accessing application services at indexing time. Pass null! for the parameter in the registration expression; the framework injects the real service provider at invocation time.

public static class ProductPageComputedFields
{
    public static int ComputedChildCount(this ProductPage page, IServiceProvider sp = null!)
    {
        var loader = sp.GetRequiredService<IContentLoader>();
        return loader.GetChildren<IContent>(page.ContentLink).Count();
    }
}

conventions.ForInstancesOf<ProductPage>()
    .IncludeField(p => p.ComputedChildCount());

Async computed fields

For I/O-bound operations, computed fields can return Task<T>. Async methods must accept a CancellationToken parameter. Use default for the cancellation token in the registration expression.

public static class ProductPageComputedFields
{
    public static Task<string> ComputedSlugAsync(
        this ProductPage page,
        CancellationToken cancellationToken = default)
    {
        return Task.FromResult(
            page.ProductName?.ToLowerInvariant().Replace(' ', '-') ?? "untitled");
    }
}

conventions.ForInstancesOf<ProductPage>()
    .IncludeField(p => p.ComputedSlugAsync());

Supported method signatures

The framework auto-detects IServiceProvider and CancellationToken parameters. The expression passed to IncludeField is used only as a method selector. Argument values are discarded and injected by the framework at invocation time.

The following method signatures are supported:

Signature	Notes
T Method()	Simple synchronous
T Method(IServiceProvider sp)	With service injection
Task<T> MethodAsync(CancellationToken ct)	Async
Task<T> MethodAsync(IServiceProvider sp, CancellationToken ct)	Async with services
static T Method()	Static method
static T Method(this TContent content)	Extension method
static T Method(this TContent content, IServiceProvider sp)	Extension with services
static Task<T> MethodAsync(this TContent content, CancellationToken ct)	Async extension
static Task<T> MethodAsync(this TContent content, IServiceProvider sp, CancellationToken ct)	Async extension with services

Supported return types

The following return types are supported for computed fields. POCO (plain C# object) return types are covered in the POCO components section.

Return type	Graph type	Example
string	String	"hello"
int, long	Int	42
float, double, decimal	Float	3.14
bool	Boolean	true
DateTime	DateTime	DateTime.UtcNow
DateTimeOffset	DateTime	DateTimeOffset.UtcNow
XhtmlString	Rich text	Rendered HTML
IEnumerable<T>	[T]	["a", "b"]
List<T>	[T]	[1, 2, 3]
POCO class	Component	Nested object
List<TPoco>	[Component]	List of nested objects
Nullable value types	Same as base	int? → Int

Warning Use simple, fast methods to avoid issues when syncing content to Optimizely Graph.

Use IncludeField to add data to a content item that does not belong to CMS content. Do not return CMS data such as ContentReference, ContentArea, Blob, or BlockData because many features associated with those data types do not work with computed fields.

IncludeField does not support methods that return the following CMS types:

Blob

ContentArea

ContentAreaItem

ContentReference

LinkItem

LinkItemCollection

PageData

BlockData

MediaData

Computed fields and type inheritance

Computed fields configured on a content type automatically appear on all derived content types. Register a computed field on a base type to include it on every content type that inherits from it when indexed to Optimizely Graph.

public class BasePage : PageData { }

public class ArticlePage : BasePage
{
    public virtual string Heading { get; set; }
}

public class NewsPage : BasePage
{
    public virtual DateTime PublishDate { get; set; }
}

public static class BasePageComputedFields
{
    public static string ComputedSection(this BasePage page) => "default";
}

conventions.ForInstancesOf<BasePage>()
    .IncludeField(p => p.ComputedSection());

ArticlePage and NewsPage include ComputedSection in their indexed content without additional configuration. Query it on any of the derived types:

{
  ArticlePage {
    items {
      Heading
      ComputedSection
    }
  }
  NewsPage {
    items {
      PublishDate
      ComputedSection
    }
  }
}

Computed fields on contracts

Register a computed field once on a content type contract instead of on each content type that implements it. Every implementing content type includes the field in its Optimizely Graph index. A contract is a C# interface that inherits from IContentData and has the [ContentType] attribute. Computed fields on contracts require CMS 13.1.1 or later and apply only to contracts defined in code.

[ContentType(GUID = "B2F0A6C4-6D7E-4A51-9C3B-1E8F2D4A7C90")]
public interface IArticle : IContentData
{
    string Summary { get; set; }
}

public static class ArticleComputedFields
{
    public static int SummaryWordCount(this IArticle article) =>
        article.Summary?.Split(' ', StringSplitOptions.RemoveEmptyEntries).Length ?? 0;
}

conventions.ForInstancesOf<IArticle>()
    .IncludeField(a => a.SummaryWordCount(), IndexingType.Queryable);

Contract computed fields support the same method signatures and return types as other computed fields. These include async methods and plain C# object (POCO) components. In the Graph C# SDK, query the field through the contract type or through any content type that implements it.

POCO components

When a computed field returns a POCO (plain C# object), the framework automatically registers it as a Graph component type and discovers its public properties.

public class ProductSummary
{
    public string Title { get; set; } = "";
    public decimal Price { get; set; }
    public bool InStock { get; set; }
}

public static class ProductPageComputedFields
{
    public static ProductSummary ComputedSummary(this ProductPage page) => new()
    {
        Title = page.ProductName,
        Price = (decimal)page.Price,
        InStock = true
    };
}

conventions.ForInstancesOf<ProductPage>()
    .IncludeField(p => p.ComputedSummary());

After ProductPage syncs to Optimizely Graph, query the nested component:

{
  ProductPage {
    items {
      ProductName
      ComputedSummary {
        Title
        Price
        InStock
      }
    }
  }
}

Control indexing on POCO properties

Control POCO property indexing with IndexingTypeAttribute:

public class ProductSummary
{
    [IndexingType(IndexingType.Searchable)]
    public string Title { get; set; } = "";

    [IndexingType(IndexingType.Queryable)]
    public decimal Price { get; set; }
}

Lists of POCOs

Computed fields can also return lists of POCOs:

public class ProductTag
{
    public string Name { get; set; } = "";
    public int Weight { get; set; }
}

public static class ProductPageComputedFields
{
    public static List<ProductTag> ComputedTags(this ProductPage page) =>
    [
        new() { Name = "electronics", Weight = 10 },
        new() { Name = "sale", Weight = 5 }
    ];
}

Multiple language support with computed fields

Give computed fields language-specific values by accessing the content item's language at indexing time. The following example returns a language-specific terms and conditions link.

[ContentType]
public class StandardPage : PageData { }

public static class StandardPageComputedFields
{
    public static string TermsAndConditions(this StandardPage page)
    {
        var language = page.Language.Name;
        var tncLink = "https://ourcorp/tnc";
        var tnc = "Terms and conditions";
        switch (language)
        {
            case "sv":
                tnc = "villkor";
                break;
        }
        return $"{tnc}: {tncLink}";
    }
}

conventions.ForInstancesOf<StandardPage>()
    .IncludeField(p => p.TermsAndConditions());

When a StandardPage has multiple versions in different languages, the TermsAndConditions field returns a different value for each language version.

Set indexing type for fields

Use IndexingType to control how computed fields are indexed. Specify this as the second parameter of IncludeField.

conventions.ForInstancesOf<ProductPage>()
    .IncludeField(p => p.ComputedTitle(), IndexingType.Searchable)
    .IncludeField(p => p.TotalPrice(), IndexingType.Queryable);

The following three indexing types are available for indexing conventions:

Searchable – The property is searchable using full-text search. Applicable only to leaf properties of XhtmlString or primitive types (string, int, datetime, and so on).

Queryable – The property can be filtered using operators such as eq, gt, and gte, but is not searchable when using full-text search.

Default – The system default indexing behavior is applied.

Note To set the indexing type for existing CMS properties (not computed fields), use the Admin UI under Settings > Content Types. Select the content type, then configure the Property Indexing Type for each property.

Query computed fields with the Graph C# SDK

Query computed fields with the same strongly typed expressions you use for CMS properties, without writing GraphQL by hand. In CMS 13.1.1 and later, the Graph C# SDK maps a computed field method call to its indexed Graph field. Use computed fields to filter, sort, facet, and autocomplete.

var result = await _graphClient
    .QueryContent<ProductPage>()
    .Where(x => x.TotalPrice() > 100)
    .OrderBy(x => x.ComputedTitle(), OrderDirection.Ascending)
    .GetAsContentAsync();

To filter on a POCO component property, call the computed field method and access the property, such as x.ComputedSummary().Price > 100. The POCO property needs its own Queryable or Searchable indexing type, as shown in the Control indexing on POCO properties section. For an async computed field, add .Result to the method call, such as x.ComputedSlugAsync(default).Result == "product-slug".

The SDK checks the indexing type of each computed field while it builds the query, before it sends the request. Each operation has its own requirement:

Filter – Register the field with IndexingType.Queryable or IndexingType.Searchable. A field with IndexingType.Default throws a NotSupportedException.

Sort – Register the field with any of the three indexing types, including IndexingType.Default.

Facet – Register the field with IndexingType.Queryable or IndexingType.Searchable. Other fields throw an InvalidFacetFieldException.

Autocomplete – Register the field with IndexingType.Queryable, and return string or Task<string>. A field with IndexingType.Searchable throws an InvalidAutocompleteFieldException.

A computed field method without an IncludeField registration throws a NotSupportedException in any query.

Best practices

Use extension methods – Define computed fields as extension methods in a separate static class to keep indexing logic separate from the content model. This improves testability and avoids polluting content types with indexing concerns.

Use descriptive method names – The method name becomes the field name in GraphQL (for example, ComputedTitle becomes ComputedTitle in queries).

Keep computations lightweight – Computed fields run during indexing for every content item. Avoid expensive operations.

Use async for I/O – If accessing external services or data, use async methods with CancellationToken.

Default parameters for injected values – Use = null! for IServiceProvider and = default for CancellationToken in method signatures.

Avoid name collisions – Computed field names must not match existing CMS property names on the same content type.

Prefer POCO components for structured data – Group related values into a POCO rather than adding many flat fields.