How can I write a custom SQL storage strategy for ObjectScript classes in IRIS?

You can implement a custom SQL/object storage mapping by using a class storage definition. Storage definitions are the mechanism that specifies the physical storage used by persistent or serial classes, and they are used when you need detailed control over storage or when mapping a class onto a preexisting data structure. [1][2]

[!NOTE]

Storage definitions are a fairly advanced feature of InterSystems IRIS® objects. In most cases, you do not need to work with storage definitions; the InterSystems IRIS class compiler automatically creates and manages storage definitions for persistent objects. [1][2]

A few key points about how they work:

• Persistent classes correspond to SQL tables, and the storage definition is the mapping between class properties and the underlying global representation. The compiler generates this mapping the first time you compile the class, and later recompiles reconcile class changes with the existing storage definition so old and new data remain accessible. [3]
• A class can have multiple storage definitions, but only one is active at a time. A new class gets a storage definition either when you compile it or when you explicitly add one. [1][2]
• You can view or edit storage definitions visually in Studio’s Storage Inspector or textually in the class body as the XML storage block. [1][2]

To define and manage custom storage definitions:

1. Create or compile your persistent class so it has a storage definition. Compiling automatically generates one for persistent and serial classes. [1][2]
2. Add or modify a storage definition for the class. Studio supports Class > Add > Storage for explicitly adding one, and the storage definition appears in the class definition body for textual editing. [1][2]
3. Maintain the storage definition as part of the class source. In UDL export, the full storage definition is included, and on import IRIS will reuse it as-is if it covers all properties and indices. This makes it suitable for versioning and deployment. [3]
4. Be careful when changing it manually. Editing the storage definition XML directly is possible, but it can make existing data inaccessible if done incorrectly. [3]

[!NOTE]

Compiling a class automatically generates its storage definition. Only persistent and serial classes have storage definitions. [1][2]

For lifecycle and schema evolution:

• Storage definitions preserve compatibility with previously stored data as class definitions change. This is why the XML block may evolve over time rather than being regenerated from scratch on every compile. [3]
• If you know there is no existing data and you want a fresh mapping, you can remove the storage definition from the class and let the compiler generate a new one. [3]

If your goal is a denormalized or sparse-matrix-style mapping, the relevant supported path is to use a custom storage definition for that persistent class. The sources explicitly describe this as appropriate when you need detailed control over storage or are mapping to an existing nondefault structure. [1][2]

[!IMPORTANT]

InterSystems® Studio has been deprecated. Beginning with version 2024.2, it is no longer included with installations of InterSystems IRIS®, and it is no longer receiving maintenance updates. An upgrade to InterSystems IRIS 2024.2 or later will remove any Studio installation which is associated with the instance. [1][2]

One important practical note: UDL includes the storage definition block, so if you are managing custom storage definitions, keep that block under source control because it is part of the compatibility contract between your class/table definition and stored data. [3]

Your note is correct: "g" is a synonym for the GOTO ObjectScript command. [4]

Sources: