Skip to content

chore: Explicit no-convenience; Add code usage examples #340

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
newtork wants to merge 5 commits into
base: main
Choose a base branch
from
+42 −6
Open

chore: Explicit no-convenience; Add code usage examples #340

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
13780df
Update warning about generated classes in prompt registry
newtork Jan 7, 2026
c29e333
Update warning about model and client packages
newtork Jan 7, 2026
c576534
Enhance document-grounding.mdx with Vector API examples
newtork Jan 7, 2026
b515e4d
Add Vector API examples for collection and document creation
newtork Jan 7, 2026
0e95f7e
Apply suggestions from code review
newtork Jan 7, 2026
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
41 changes: 38 additions & 3 deletions docs-java/ai-core/document-grounding.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,10 @@ This guide provides examples on how to manage data in [SAP Document Grounding](h
It's divided into two main sections: Data Ingestion and Data Retrieval.

:::warning
All classes under any of the `...model` packages are generated from an OpenAPI specification.
This means that these model classes are not guaranteed to be stable and may change with future releases.
They are safe to use, but may require updates even in minor releases.
All classes in the `...model` and `...client` packages are generated from an OpenAPI specification.
These classes can be used, but no API stability guarantees are provided, even for minor releases.
Maintenance and support are limited to ensuring consistency with the service specification.
No additional convenience API layer is provided.
:::

## Prerequisites
Expand Down Expand Up @@ -78,6 +79,23 @@ PipelineStatus status = api.getPipelineStatus(resourceGroupId, pipeline.getPipel

### Vector API

Collection creation:

```
Comment on lines +82 to +84
Copy link
Contributor

@CharlesDuboisSAP CharlesDuboisSAP Jan 7, 2026

Choose a reason for hiding this comment

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

Suggested change
Collection creation:
```
#### Collection creation:
```java

String resourceGroupId;
CollectionRequest collectionRequest;

var api = new GroundingClient().vector();

OpenApiResponse documents = api.createCollection(resourceGroupId, collectionRequest);
Map<String, List<String>> headers = documents.getHeaders();

String locationHeader = headers.get("Location").get(0);
String collectionId = locationHeader.replaceAll("^.*?/([a-f0-9-]+)/.*?$", "$1");
```

Document creation:
Copy link
Contributor

@CharlesDuboisSAP CharlesDuboisSAP Jan 7, 2026

Choose a reason for hiding this comment

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

Suggested change
Document creation:
#### Document creation:


```java
var api = new GroundingClient().vector();
var resourceGroupId = "default";
Expand All @@ -96,6 +114,23 @@ var request = DocumentCreateRequest.create()
DocumentsListResponse response = api.createDocuments(resourceGroupId, collectionId, request);
Copy link
Contributor

@CharlesDuboisSAP CharlesDuboisSAP Jan 7, 2026

Choose a reason for hiding this comment

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

Document creation is not compiling

Copy link
Contributor

@CharlesDuboisSAP CharlesDuboisSAP Jan 7, 2026

Choose a reason for hiding this comment

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

var request =
    DocumentCreateRequest.create()
        .documents(
            BaseDocument.create()
                .chunks(
                    TextOnlyBaseChunk.create()
                        .content("The dog makes _woof_")
                        .metadata(VectorKeyValueListPair.create().key("animal").value("dog")))
                .metadata(VectorDocumentKeyValueListPair.create().key("topic").value("sound")));

```

Document search:
Copy link
Contributor

@CharlesDuboisSAP CharlesDuboisSAP Jan 7, 2026

Choose a reason for hiding this comment

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

Suggested change
Document search:
#### Document search:


```java
String resourceGroup;
TextSearchRequest textSearch;

var api = new GroundingClient().vector();
var result = api.search(resourceGroup, textSearch);

String joinedContent = result.getResults().stream()
.flatMap(r -> r.getResults().stream())
.flatMap(r -> r.getDocuments().stream())
.flatMap(d -> d.getChunks().stream())
.map(VectorChunk::getContent)
.collect(Collectors.joining());
```

Refer to the [GroundingController](https://github.com/SAP/ai-sdk-java/tree/main/sample-code/spring-app/src/main/java/com/sap/ai/sdk/app/controllers/GroundingController.java) in our Spring Boot application for a complete example.

## Data Retrieval
Expand Down
7 changes: 4 additions & 3 deletions docs-java/ai-core/prompt-registry.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,10 @@ keywords:
This guide provides examples on how to manage the life cycle of your prompts, from design to runtime in [Prompt Registry](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/prompt-registry).

:::warning
All classes under any of the `...model` packages are generated from an OpenAPI specification.
This means that these model classes are not guaranteed to be stable and may change with future releases.
They are safe to use, but may require updates even in minor releases.
All classes in the `...model` and `...client` packages are generated from an OpenAPI specification.
These classes can be used, but no API stability guarantees are provided, even for minor releases.
Maintenance and support are limited to ensuring consistency with the service specification.
No additional convenience API layer is provided.
:::

## Prerequisites
Expand Down