Searchable @Common.Text Annotation

guides/providing-services.md

@@ -426,6 +426,26 @@ Searches all elements of type `String` excluding the element `isbn`, which leave
 You can explicitly annotate calculated elements to make them searchable, even though they aren't searchable by default. The virtual elements won't be searchable even if they're explicitly annotated.
 :::
 
+#### The `@Common.Text` Annotation 
+
+If an entity has an element annotated with the `@Common.Text` annotation, then the property that holds the display text is by default added to the searchable elements. Example:
+
+```cds
+entity Books : cuid {
+  title  : String;
+  @Common.Text : author.name
+  author : Association to Author;
+}
+entity Author : cuid {
+  name : String;
+}
+```
+The default searchable elements of `Books` are `title` and `author.name`.
+
+::: warning
+`@cds.search` takes precedence over `@Common.Text`. As a result, `@Common.Text` is ignored as soon as `@cds.search` defines anything in an including mode (that is, not exclusively for excluding properties).
+:::
+
 #### Fuzzy Search on SAP HANA Cloud <Beta /> {#fuzzy-search}
 
 > Prerequisite: For CAP Java, you need to run in [`HEX` optimization mode](../java/cqn-services/persistence-services#sql-optimization-mode) on SAP HANA Cloud and enable <Config java keyOnly>cds.sql.hana.search.fuzzy = true</Config>