The repository you have cloned provides a skeleton project in the project directory (../../project/job-posting-service/). The skeleton project contains an already-set-up CAP application with the fully configured package.json and supporting files for the following exercises.
In this exercise you will learn:
- How to explore the
package.jsonand its contents. - How to define the database schema for the SAP HANA Cloud database.
- How to build and deploy the schema to your HDI container.
The package.json file includes all Node.js project-specific configurations like project name, version, dependencies, and run scripts but also CDS-specific configurations like the HANA runtime information.
👉 Open the package.json file.
👉 Examine the dependencies. Notice that there is a dependency for "@sap-ai-sdk/orchestration": "1.7.0" and the "@sap-ai-sdk/langchain": "1.7.0".
The SAP Cloud SDK for AI provides four different packages for you to use depending on your use case.
- @sap-ai-sdk/orchestration: The orchestration package incorporates generative AI orchestration capabilities into your AI activities in SAP AI Core and SAP AI Launchpad.
- @sap-ai-sdk/langchain: The langchain package provides LangChain model clients, built on top of the foundation model clients of the SAP Cloud SDK for AI.
- @sap-ai-sdk/foundation-models: The foundation models package incorporates generative AI foundation models into your AI activities in SAP AI Core and SAP AI Launchpad.
- @sap-ai-sdk/ai-api: The AI SDK API package provides tools to manage your scenarios and workflows in SAP AI Core.
In addition, the package.json allows you to define run scripts a sort of alias for more complex commands.
👉 Examine the listed scripts.
build: Runs thecds buildcommand to build the CAP project.build_sqlite: Builds the CAP application for usage on a SQLite database.start: Starts the CAP application.watch: Deploys your changes specific to your service to localhost using the hybrid profile, establishing a connection to your real HDI container instance.sqlite: Deploys your changes specific to your service to localhost using the hybrid profile, establishing a connection to a real SQLite database.
Within a CAP application, you can define a database schema that can be built into HANA database artifacts. The artifacts can be deployed to a bound HDI container, which will cause the creation of the database tables, relationships, views, and any other HANA database artifacts.
For this project, the schema has two entities; DocumentChunks and JobPostings.
The DocumentChunks entity contains the text chunks, embeddings for the provided context information and relevant metadata. In the exercise 07 - Define the Job Posting Service, you will define a service for creating and deleting job postings. You will use a chat model to create job postings for specific job specifications and in exercise 06 - Create Vector embeddings use an embedding model to create vector embeddings providing additional business contextual information to the chat model. This information can then be used to generate an accurate job posting utilizing internal company specific information.
👉 Open the schema.cds file under the db directory.
👉 In the file define a namespace sap.codejam:
namespace sap.codejam;The namespace allows for better identification and provides uniqueness to the entities within that namespace. It also will cause the database table to be named SAP_CODEJAM_<Entity Name> in example SAP_CODEJAM_DOCUMENTCHUNKS.
👉 Right below, add the following line of code:
using {
cuid,
managed
} from '@sap/cds/common';The entity should be managed, meaning it will utilize cuid to auto-generate a UUID, create time stamps for creation and mutation of the table entries including auditing.
👉 Add an entity to store job postings in the database. You will utilize this entity in a later exercise by using AI to generate job postings and store them in the corresponding table.
entity JobPostings : cuid, managed {
user_query : String;
rag_response : String;
}The entity defines two fields:
user_query: Stores the incoming user query.rag_response: Stores the response from the chat model.
👉 Lastly, add the definition for the DocumentChunks entity. The entity is using the managed and cuid features from the cds.common package.
entity DocumentChunks : cuid, managed {
metadata : LargeString;
text_chunk : LargeString;
embedding : Vector(1536);
}The entity defines three fields:
metadata: Stores the path to the information document. The document is a PDF that includes business contextual information.text_chunk: Stores the individual-created text chunks.embedding: Stores the encoded vector embeddings created by an embedding model.
👉 Save the file.
The complete schema.cds should look like this now:
namespace sap.codejam;
using {
cuid,
managed
} from '@sap/cds/common';
entity DocumentChunks : cuid, managed {
metadata : LargeString;
text_chunk : LargeString;
embedding : Vector(1536);
}
entity JobPostings : cuid, managed {
user_query : String;
rag_response : String;
}
Because you created a binding to our HDI container, you have all configurations in place to deploy HANA database artifacts to the instance. To do so you need to build the artifacts first enter the cds deploy command.
👉 Make sure that you are still connected to the Cloud Foundry instance by checking the connection details:
cf target
If the reply from the CLI tells you to log in again simply enter cf login.
cf login👉 Build the project first by calling the cds build --production command.
cds build --production👉 To deploy the build db artifacts in the .gen folder, call the cds deploy --to hana:<hdi-instance> command (Use the HDI container name from Exercise 04).
In case you forgot your HDI container name, you can simply call
cf servicesto get a list of all available service instances including your HDI container.
cds deploy --to hana:<your-hdi-container-name> --auto-undeployThe --auto-undeploy argument causes the database to adjust to the new runtime definition of your database artifacts.
Be aware that the command will create another service key for deployment to the HDI container. This is okay as you are using the binding for connection to the HDI container from within the CAP application.
You will see a large terminal output listing the different steps of the building and deployment process.
Great! The database is initialized, and the table with all necessary fields is created.
There are multiple ways of viewing your database artifacts on SAP HANA Cloud. One would be to use the SAP HANA Database Explorer and, of course, the CLI if you don't want to use the UI. If you are interested in using the SAP HANA Database Explorer, you will find a tutorial in the Further Reading section. You should use the CLI today because it is faster. #TheFutureIsTerminal
You have to install the hana-cli first.
👉 Open a new terminal or use an existing one.
👉 Run the install command:
npm install -g hana-cliNote that you install the HANA CLI globally here. You can always install the CLI for the project only and remmove the
-gargument. If you want to use the HANA CLI in multiple projects it makes sense to install it globally.
👉 Enter the hana-cli help command to get a list of all available commands:
hana-cli help👉 To get a list of all available tables within your HDI container you can execute the following command:
hana-cli tables
From the response, you can extract the schema name and the table name. You will use the information to fetch all information about that table. Be aware, sometimes if you copy the schema and table name from the previous CLI response it might add special characters which are not part of the name. You need to delete them.
👉 Enter the following command to list the table information:
hana-cli inspectTable <Your-schema-name> SAP_CODEJAM_DOCUMENTCHUNKS
You can see all created fields as defined in the schema.cds. Notice that it also has all the fields from the managed feature from the cds.common package.
👉 Go ahead and try inspecting the job postings table.
At this point, you have learned how to define a database schema using CDS, how to build and deploy database artifacts, and how you can use the hana-cli to inspect your database tables.
- How do you define a database schema in a CAP application, and what entities are included in this exercise?
Answer
In a CAP application, you define the database schema using a schema.cds file. This file specifies the entities that represent database tables, their fields, and relationships. In this exercise, two key entities are defined:-
DocumentChunks: Stores text chunks, vector embeddings, and relevant metadata for business context.
-
JobPostings: Stores job posting data, including the user query and the response generated by a chat model.
- What is the command to build and deploy the database schema to the HDI container, and what steps must you follow?
Answer
To build and deploy the database schema to the HDI container, follow these steps:- Build the project with the command:
cds build --production- Deploy the database artifacts using:
cds deploy --to hana:<your-hdi-container-name> --auto-undeployThe --auto-undeploy flag ensures that the database is updated according to the new schema.
- How can you inspect the deployed database tables in your HDI container using the CLI?
Answer
You can inspect the deployed database tables using the hana-cli tool. After installing it, follow these steps:- Run the command to view available tables::
hana-cli tables- To inspect a specific table, such as the DocumentChunks table, use:
hana-cli inspectTable <Your-schema-name> SAP_CODEJAM_DOCUMENTCHUNKSThis will display the schema and fields of the DocumentChunks table, allowing you to verify the deployment. You can also inspect the JobPostings table in a similar manner.