Here’s the first of a series of posts on the thinking behind FMQL’s structure. I want to focus on its more detailed options, but first, let me review the straightforward.

FMQL presents a querier with three operations: COUNT, SELECT and DESCRIBE. Basic COUNT is obvious …

COUNT 2

returns the number of instances of type “2″.

“Type 2″? In FileMan, “2″ is the patient type which means this query counts the number of patients in FileMan. You may ask why FMQL uses numeric identifiers and not labels like “Patient” or “Problem”? Well, FileMan has over five thousand types of thing and their labels are sometimes ambiguous and even recycled. Yes, using identifiers forces a querier to lookup schema definitions but that’s easy with the Schema Browser client.

BTW, FileMan’s documents talk about files with records which have fields. Back when the VA made this MUMPS-based data store, file systems were very much in vogue. Today, we talk about types with instances that have attribute values and that’s how I’ll describe FileMan data and how FMQL accesses it.

SELECT 2

SELECT returns identifiers of instances of a type. This SELECT identifies all of the patients in a VistA in markup like …

   "uri": {
    ...
    "value": "2-1",
    "type": "uri",
    "label": "PATIENT/ZZTEST,ONE"
   }

This is JSON, the well known, web-friendly data format. JSON is FMQL’s native response format and we picked it because it is easy to process in any modern programming or scripting language.

Back to this content. Identifiers are called uri in FMQL; “value” give the actual identifier – “2-1″ means the first instance in type 2. And look at “label”: all uri’s in FMQL get labels. This makes it easy to display them in a web page and enables a coder to read FMQL’s JSON output.

DESCRIBE 2-9

DESCRIBE 2-9 returns more than the identifier of 2-9. It gives its other attributes too. For example …

"place_of_birth_state": {
    ...
    "value": "5-39",
    "type": "uri",
    "label": "STATE/OHIO",
    ...
   },

place of birth is given by the uri for “OHIO”, “5-39″ – OHIO is defined by the 39th instance of 5, the STATE type. FileMan is very uri-centric and most attribute values reference. Of course, some just contain string values which are of type “literal” …

"occupation": {
    ...
    "value": "STOCKBROKER",
    "type": "literal"
   },

Why does FileMan enumerate STATEs and leave occupation as a string? Beats me.

Ok, that’s it for FMQL basics. Three operations. You get back JSON with “uri” and “literal” values.