Skip to content

Searchable @Common.Text Annotation #2041

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Searchable @Common.Text Annotation #2041

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
3bcaf75
searchable @Common.Text
OlenaTi Aug 20, 2025
a478fdd
Merge branch 'main' into otimrova/common-text-annotation
etimr Aug 21, 2025
ef2ba29
review fix
etimr Aug 22, 2025
19a843d
Merge branch 'main' into otimrova/common-text-annotation
etimr Aug 22, 2025
ed25aa1
review fix
etimr Aug 22, 2025
c4e8f89
Merge branch 'main' into otimrova/common-text-annotation
etimr Aug 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions guides/providing-services.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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:
The `@Common.Text` annotation allows you to specify a property that holds a text to be displayed on the UI instead of the value of the annotated property. To enhance the user experience, the property that holds the display text is searched by default:

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@MattSchur the subsection The @Common.Text Annotation belongs to the Searching Data section, right after @cds.search. I think @Common.Text should be described here only from the search perspective, not as UI annotation.

If we need to describe what @Common.Text means as UI annotation, we can add it here https://cap.cloud.sap/docs/advanced/odata, where it mentioned several times.

Also the exact same text is used in the Java release notes and will be used in the Node release notes as well with the link to this documentation. I think it should be rephrased with the focus on the search.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, I didn't notice that this is a subsection of Search


```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`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The default searchable elements of `Books` are `title` and `author.name`.
Here the value of the name property of the Authors entity is displayed on the UI instead of the author association and is also searched automatically, without requiring additional configuration.


::: warning
Do not use both `@cds.search` and `@Common.Text` annotations on the same entity, unless `@cds.search` is used only to exclude fields. If both are present and `@cds.search` includes fields, the `@Common.Text` annotation will be ignored.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this specific to @Common.Text? AFAIK @cds.search with include fields overrides all default search elements

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this specific to @Common.Text? AFAIK @cds.search with include fields overrides all default search elements

@cds.search: { author } will add all searchable elements of the associated Authors entity to all searchable elements of the Books entity, not overwrite them. Mentioning explicitly, that @cds.search with included fields has a priority over @Common.Text, allows to avoid confusion in the case both annotations are used.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I add @cds.search: { description }, is title still searched?

:::

#### 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>
Expand Down
Loading