Topic outline

• Exploring Multiple Data Models with Globals

  Exploring Multiple Data Models with Globals

  InterSystems IRIS® data platform contains an extremely efficient data model known as globals. Data added to globals is immediately stored and available to multiple processes, not just the process that stored it.

  A global is a persistent multidimensional array of nodes. Nodes referred to as leaf nodes contain only data. Some nodes contain a set of child nodes, which is why globals are typically depicted as a hierarchical tree.

  A subscript is an identifier for a child node. A unique subscript must specify each child node of the parent because child nodes are in the same subscript level or dimension of the global. Likewise, a list of subscripts specifies a unique node within a multi-level or multidimensional global.

  The benefits of using globals are vast—some are listed below.

  • Efficient: Globals grow based on need, without upfront declaration of size or structure.
  • Multimodel: Leaf nodes can store objects, tables and indexes, JSON and XML documents, even documentation.
  • Typeless: Subscripts, even those at the same subscript level, can be integers, strings, and decimals.
  • Automatically sorted: Globals sort subscripts automatically at each dimension.
  • Flexible: Globals allow flexibility in node structure and data storage to contain any number of subscripts and any type of data.
  • Safe: You can lock any node to keep other processes from changing value while keeping other nodes at same level accessible.

  Note that globals are not just another storage model. In fact, they are so powerful and flexible that they are actually at the core of all InterSystems models, giving you freedom from database remodels.

  In this exercise, you will examine the globals used to store data for objects of a class of U.S. states. Properties of the class include the name of the state, its two-letter postal abbreviation, its capital, the year it was established, and its area (in square miles). Then you will access and store objects of this class using relational and object techniques, as well as by manipulating the globals directly.
• Collapse allExpand all
  Try It

  Try It

  This example demonstrates how globals are used to store data for objects of the U.S. state class. A state's name, postal abbreviation, capital city, year it was founded, and area (in square miles) are among the properties of the class. In addition to manipulating global variables directly, you will use relational and object techniques to access and store objects of this class.
  

  •  You must be logged in to launch an InterSystems IRIS instance.

    • Log in with your existing account.
    • Don't have an InterSystems account? Create a new account.
  • Find the class

    The lab for this exercise contains a class called FirstLook.State.
    

    Let's begin by opening the class in our IDE.

    1. Click the IDE link in the launcher above.
    2. Click Yes to define the author as trusted.
    3. Click Allow to sign in using InterSystems server credentials.
    4. Type the password demo in the prompt.
    5. Click the InterSystems icon.
    6. Go to Classes > FirstLook > State.cls.
    7. Click Allow to grant permission for the extension to access the InterSystems Server Credentials
       

    
    

    Notice that the class extends %Persistent. This allows the data to be saved to the database. This class also has the following properties for each U.S. state:

    • Name: The name of the state
    • PostalAbbr: The postal abbreviation for the state
    • Capital: The name of the state's capital
    • Established: The year the state joined the union
    • Area: The size of the state in square miles

    
    

    Additionally, this class contains two indices—CapitalIndex and PostalAbbrIndex—which can be used to quickly locate states by capital and postal abbreviation using SQL queries.

    In the Storage section, the <DataLocation> keyword displays the name of the global where the data is stored, while the <IndexLocation> keyword indicates the location where the indexes are saved.
    

  • Find the global

    Example data has been preloaded into the FirstLook.StateD global using the class in Task 1. Now, we will view the information in the Management Portal.

    1. Click the Management Portal link.
    2. Select System Explorer > Globals.
    3. In the Global name box, type F* to filter for all globals that start with F. Then press Tab.
    4. Click the View link in the ^FirstLook.StateD row to show the contents of this global.

    You will see 14 rows, all but the first having an associated ID. For example, ID 7 represents Maryland. Note that the first row represents the last ID we added to the global; in this example, 13.

    

  • Access the global using SQL

    There are four ways to access globals: via SQL, objects, direct access, or API access. This exercise will cover three of them, but it is important to know that no one method is superior to the others. The best way to access a global will depend on your preference.

    To access a global through SQL in the Management Portal:

    1. From the Management Portal home page, select System Explorer > SQL.
    2. In the left column, expand the Tables section to view the tables in the namespace.
    3. Under Tables, select the FirstLook.State table.
    4. On the Catalog Details tab, click Fields. You will see a field generated for each property of the State class, plus an additional field called ID, also known as RowID. This field is similar to the object ID you saw in the globals for the class.
    5. Click the Execute Query tab to open a text area where you can write queries to run against the FirstLook.State table.
    6. Type the following query:
       Begin code.

       SELECT * FROM FirstLook.State WHERE ID = 6

       End code.
    7. Click Execute. The query will return the row you requested, for the state of Massachusetts.
    8. Type the following query and click Execute:
       Begin code.

       INSERT INTO FirstLook.State(Area, Capital, Established, Name, PostalAbbr) VALUES (9616, 'Montpelier', 1791, 'Vermont', 'VT')

       End code.
       This will insert a row into the table for Vermont, the 14th state.

    Note:

    Examine the contents of the global ^FirstLook.StateD again, as you did in Task 2 (Remember to type F* to filter). You will see that the ID counter has increased to 14 (^FirstLook.StateD = 14), and there is a new row with the Vermont information: Begin code.^FirstLook.StateD(14) = $lb("","Vermont","VT","Montpelier",1791,9616)End code..
  • Access the global as an object

    Globals are very flexible and can be accessed in a relational manner using SQL, as you saw in Task 3, or as an object, as you will see here. This flexibility is why globals are so powerful and come highly recommended.

    To access and manipulate global data as an object:

    1. From the lab launcher above, click the WebTerminal link.
    2. Sign in using the following credentials:
       • Username: tech
       • Password: demo
    3. Set a variable called vt to retrieve the Vermont information by including the FirstLook.State class and the ID 14: Begin code.

       set vt = ##class(FirstLook.State).%OpenId(14)

       End code.
    4. Verify that the correct data was retrieved by calling the Name property of the vt variable: write vt.Name
    5. View a summary of all the object's properties by using the zwrite command: zwrite vt
    6. Create a new state object using the %New() method: Begin code.

       set newstate = ##class(FirstLook.State).%New()

       End code.
    7. Set the properties for Kentucky:
       • set newstate.Name = "Kentucky"
       • set newstate.PostalAbbr = "KY"
       • set newstate.Capital = "Frankfort"
       • set newstate.Established = 1792
       • set newstate.Area = 40408
    8. Verify that the information is correct: zwrite newstate
       A table is displayed with two sections. The first section, labeled "General Information," presents the global name and reference count. The second section, "Attribute Values," presents recently entered information for Kentucky.
    9. Save the new state in the global: set status = newstate.%Save()
    10. Verify that the new data was saved by typing write status.
        A value of 1 indicates a successful save.

    Note:

    The newstate variable will not be part of the global until you use the %Save() method.
  • Accessing globals directly

    Although data in InterSystems IRIS is usually accessed through SQL or the object layer, you can also directly access globals for classes that extend %Persistent. However, this method is more complex because you need to be familiar with the structure of the global.

    To access and manipulate global data directly:

    1. Assign the ky variable to the node in the data global with subscript 15: set ky = ^FirstLook.StateD(15)
       Note that in this case, we do not use the class or the %OpenId() method because we are not retrieving the value as an object.
    2. Use the zwrite command to view the value of the ky variable. Notice that the result is shown as a list.
    3. Use the $list() function to get the second item in the list: write $list(ky, 2)
       
    4. To add a new state using this method, first set a variable for each property as shown below. Recall that to do this in your own system, you have to know the global structure.
       • set name = "Tennessee"
       • set postalabbr = "TN"
       • set capital = "Nashville"
       • set established = 1796
       • set area = 42144
    5. Use the $listbuild() function to build a list of properties that can be stored: Begin code.

       set properties = $listbuild("", name, postalabbr, capital, established, area)

       End code.
    6. Increment the ID counter of the ^FirstLook.StateD global and assign the new value to the variable id.
       Note that this is not automatic, like in the relational or object ways of accessing the data. Type: Begin code.

       set id = $increment(^FirstLook.StateD)

       End code.
    7. Store the data in the data global: set ^FirstLook.StateD(id) = properties
    8. Manually update the indices; otherwise an SQL query with a WHERE clause on Capital or PostalAbbr will not include the state of Tennessee. Concatenate a space to the front of the capitalvariable using the _ operator and then convert it to uppercase with the $zconvert() function:
       • set capital = $zconvert(" "_capital, "U")
       • set postalabbr = $zconvert(" "_postalabbr, "U")
    9. Finally, store the index entries in the index global:
       • set ^FirstLook.StateI("CapitalIndex", capital, id) = ""
       • set ^FirstLook.StateI("PostalAbbrIndex", postalabbr, id) = ""

    As you can see, there are several ways to access globals, so you can choose the one that is best for your situation.

• What's next?

  What's next?

  Continue learning with the following resources:

  • Watch an introduction to globals (video, 15m).
  • Experience data model flexibility in InterSystems IRIS (exercise, 5m).
  • Build a server-side application in InterSystems IRIS (learning path, 2h).
    

  • Share Your Feedback!