POCO Index IndexProvider mapping

🔒 You must be logged in as an Administrator or Editor to listen to this audio.

Here is a breakdown of how these three files work together to manage data within Orchard Core, along with a guide to the foundational YesSql concepts they rely on.

The Relationship Between the Files

In Orchard Core, data is managed by YesSql, a document database that runs on top of traditional relational databases (like SQL Server, SQLite, or PostgreSQL). The three files you provided form the complete lifecycle of storing, indexing, and querying a specific piece of data:

  • The Model (AIProfile.cs): This is your complete data payload. It holds everything about the AI configuration, including complex nested data like the JsonObject Settings and legacy fallback fields like ConnectionName. YesSql takes this entire object and serializes it into a single JSON string, storing it in a central Document table.
  • The Blueprint (AIProfileIndex.cs): Because querying raw JSON in a database is slow, you need a way to look up profiles quickly. This file defines a lightweight, flat SQL table schema containing only the fields you will actually need to search or filter by, such as Name, Type, or OrchestratorName.
  • The Translator (AIProfileIndexProvider.cs): This file acts as the bridge. It tells YesSql exactly how to extract data from the complex JSON document (AIProfile) and push it into the flat SQL table (AIProfileIndex). For example, it maps the ChatDeploymentId from the profile directly to the DeploymentId column in the index.

Core YesSql Concepts Explained

To truly master Orchard Core module development, it is essential to understand these three architectural pillars.

1. POCO (Plain Old C# Object)

A POCO is a simple class that acts as a data container, completely unaware of the database.

  • In this context: AIProfile.cs is the POCO.
  • How it works: You do not need to use [Table] or [Column] attributes to map it to a database. YesSql treats your POCO as a document. You can add complex types (like lists, dictionaries, or dynamic JSON nodes) without worrying about how to structure a SQL table for them.

2. Index

An Index in YesSql is an optimization tool that solves the problem of searching through JSON documents.

  • In this context: AIProfileIndex.cs defines the Index.
  • How it works: It generates a real, physical SQL table in your database. However, this table does not hold the primary truth of your data; it acts as a directory. When your code needs to find an AIProfile created by a specific user, it queries the AIProfileIndex table for the OwnerId, finds the associated document ID, and then pulls the full JSON document.

3. Index Provider

The Index Provider is the event-driven engine that keeps the Index SQL tables synchronized with your JSON documents.

  • In this context: AIProfileIndexProvider.cs is the provider.
  • How it works: It uses a Map/Reduce pattern. Whenever you save an AIProfile document to the database, the Describe method is triggered. The .Map() function executes, reading the properties of the document and returning a new instance of the Index class. It can even perform complex extractions, like deserializing the Settings property into an AIProfileSettings object just to grab the IsListable boolean for the SQL column.

Would you like to explore how to write the actual YesSql queries in a service class to fetch an AIProfile using this newly created index?