This function is to parse your schema. The return values are passed to the other two functions to interpret your schema. You can declare and define your schema with tuples and lists without reading a json file as defined in below function, but you will not receive type and duplicate checking from this function.

Schema:

The schema json file is formated as one json object to describe the GraphQL objects and the object heirarchy. Only PrimitiveObjects are valid descendants to ParentalObjects. Only the shared object fields and shared scalar fields are parental object fields. If a parental object is a declared field from a primitive object, all descendants are supposed to be declared in database relationships. When declaring any primitive or parental object, the pseudonym is supposed to list all possible root object references. As a nested object, you should declare the names in the nested object field definitions in corresponding object definitions. Primitive objects are expected to not have all NULL unique id values, and they are otherwise removed from the result. Database relationships are defined as an ordered sequence from the identity table to the target association table. The order is identity table, identity table join field(s), target table, target table join field(s), then (multiple) triplets (of intermediate table, intermediate table to-join field, then intermediate table from-join field in order of nearness from identity table) if relevant. If multiple fields are defining the join, one declares every field with a space " " separation. For example, the declaration is [A,"a b", B, "c d"] if the join condition is A.a=B.c and A.b = B.d. You can add schema associations as declaring more object-fields in the primitive objects.

Scalar fields:

Scalar fields are declared with a type, and they are cast to corresponding JSON format when making the GraphQL result. Valid scalar field types are Text, ByteString, Int, Double, Rational, Bool, Day, TimeOfDay, or UTCTime.

Function exceptions:

Exceptions are returned when error is faced. This method returns errors of:

• ImportSchemaException (if there is a problem with reading your schema)
• ImportSchemaServerNameException (if there is a problem with reading your servername argument)
• ImportSchemaPseudonymsException (if there is a problem with reading your pseudonyms list argument)
• ImportSchemaScalarFieldsException (if there is a problem with reading your scalarfields list argument)
• ImportSchemaObjectFieldsException (if there is a problem with reading your objectfields list argument)
• ImportSchemaDatabaseTablesException (if there is a problem with reading your databasetables list argument)
• ImportSchemaDatabaseRelationshipsException (if there is a problem with reading your databaserelationships list argument)
• ImportSchemaDuplicateException (if two or more Server objects are sharing the same name)

Schema format example:

Here is an example schema to look at formatting:

   {
     ParentalObjects:[
       {
         ServerName:Taxonomy,
         Pseudonyms:[
           "taxonomy",
           Taxonomy
         ],
         ServerChildren:[
           Breed,
           Species,
           Family,
           Genus
         ]
       }
     ],
     PrimitiveObjects:[
       {
         ServerName: Person,
         Pseudonyms: [
           "person",
           Person
         ],
         ScalarFields: [
           {
             Name: "id",
             Type: Int,
             Arguments: []
           },
           {
             Name: "name",
             Type: Text,
             Arguments: []
           },
           {
             Name: "gender",
             Type: Int,
             Arguments: [
               {
                 Name: "as",
                 Options: [
                   {
                     Name: MALEFEMALE,
                     Type: Text,
                     Prefix: "CASE WHEN ",
                     Suffix: "==1 THEN MALE ELSE FEMALE END"
                   }
                 ]
               }
             ]
           }
         ],
         ObjectFields: [
           {
             Names: [
               "pet"
             ],
             ServerName: Pet
           },
           {
             Names: [
               "breed"
             ],
             ServerName: Breed
           },
           {
             Names: [
               "species"
             ],
             ServerName: Species
           },
           {
             Names: [
               "genus"
             ],
             ServerName: Genus
           },
           {
             Names: [
               "family"
             ],
             ServerName: Family
           },
           {
             Names: [
               "taxonomy"   
             ],
             ServerName: Taxonomy
           }
         ],
         DatabaseTable: "person",
         UniqueIds: [
           "id"
         ],
         DatabaseRelationships: [
           ["person","id","pet","id","pet_ownership","owner_id","animal_id"],
           ["person","id","breed","id","pet_ownership","owner_id","animal_id","pet","id","id","pet_type","pet_id","breed_id"],
           ["person","id","species","id","pet_ownership","owner_id","animal_id","pet","id","id","pet_type","pet_id","breed_id","breed","id","species_id"],
           ["person","id","genus","id","pet_ownership","owner_id","animal_id","pet","id","id","pet_type","pet_id","breed_id","breed","id","species_id","species","id","genus_id"],
           ["person","id","family","id","pet_ownership","owner_id","animal_id","pet","id","id","pet_type","pet_id","breed_id","breed","id","species_id","species","id","genus_id","genus","id","family_id"]
         ]
       },
       {
         ServerName: Family,
         Pseudonyms: [
           Family,
           "family"
         ],
         ScalarFields: [
           {
             Name: "id",
             Type: Int,
             Arguments: []
           },
           {
             Name: "name",
             Type: Text,
             Arguments: []
           }
         ],
         ObjectFields: [
           {
             Names: [
               "genus"
             ],
             ServerName: Genus
           },
           {
             Names: [
               "species"
             ],
             ServerName: Species
           },
           {
             Names: [
               "breed"
             ],
             ServerName: Breed
           },
           {
             Names: [
               "pet"
             ],
             ServerName: Pet
           },
           {
             Names: [
               "person"
             ],
             ServerName: Person
           }
         ],
         DatabaseTable: "family",
         UniqueIds: [
           "id"
         ],
         DatabaseRelationships: [
           ["family","id","person","id","genus","family_id","id","species","genus_id","id","breed","species_id","id","pet_type","breed_id","pet_id","pet_ownership","animal_id","owner_id"],
           ["family","id","pet","id","genus","family_id","id","species","genus_id","id","breed","species_id","id","pet_type","breed_id","pet_id"],
           ["family","id","genus","family_id"],
           ["family","id","species","genus_id","genus","family_id","id"],
           ["family","id","breed","species_id","genus","family_id","id","species","genus_id","id"]
         ]
       },
       {
         ServerName: Genus,
         Pseudonyms: [
           Genus,
           "genus"
         ],
         ScalarFields: [
           {
             Name: "id",
             Type: Int,
             Arguments: []
           },
           {
             Name: "name",
             Type: Text,
             Arguments: []
           }
         ],
         ObjectFields: [
           {
             Names: [
               "family"
             ],
             ServerName: Family
           },
           {
             Names: [
               "species"
             ],
             ServerName: Species
           },
           {
             Names: [
               "breed"
             ],
             ServerName: Breed
           },
           {
             Names: [
               "pet"
             ],
             ServerName: Pet
           },
           {
             Names: [
               "person"
             ],
             ServerName: Person
           }
         ],
         DatabaseTable: "genus",
         UniqueIds: [
           "id"
         ],
         DatabaseRelationships: [
           ["genus","id","person","id","species","genus_id","id","breed","species_id","id","pet_type","breed_id","pet_id","pet_ownership","animal_id","owner_id"],
           ["genus","id","pet","id","species","genus_id","id","breed","species_id","id","pet_type","breed_id","pet_id"],
           ["genus","family_id","family","id"],
           ["genus","id","species","genus_id"],
           ["genus","id","breed","species_id","species","genus_id","id"]
         ]
       },
       {
         ServerName: Species,
         Pseudonyms: [
           Species,
           "species"
         ],
         ScalarFields: [
           {
             Name: "id",
             Type: Int,
             Arguments: []
           },
           {
             Name: "name",
             Type: Text,
             Arguments: []
           }
         ],
         ObjectFields: [
           {
             Names: [
               "family"
             ],
             ServerName: Family
           },
           {
             Names: [
               "genus"
             ],
             ServerName: Genus
           },
           {
             Names: [
               "breed"
             ],
             ServerName: Breed
           },
           {
             Names: [
               "pet"
             ],
             ServerName: Pet
           },
           {
             Names: [
               "person"
             ],
             ServerName: Person
           }
         ],
         DatabaseTable: "species",
         UniqueIds: [
           "id"
         ],
         DatabaseRelationships: [
           ["species","id","person","id","breed","species_id","id","pet_type","breed_id","pet_id","pet_ownership","animal_id","owner_id"],
           ["species","id","pet","id","breed","species_id","id","pet_type","breed_id","pet_id"],
           ["species","id","breed","species_id"],
           ["species","genus_id","genus","id"],
           ["species","id","family","genus_id","genus","species_id","id"]
         ]
       },
       {
         ServerName: Breed,
         Pseudonyms: [
           Breed,
           "breed"
         ],
         ScalarFields: [
           {
             Name: "id",
             Type: Int,
             Arguments: []
           },
           {
             Name: "name",
             Type: Text,
             Arguments: []
           }
         ],
         ObjectFields: [
           {
             Names: [
               "family"
             ],
             ServerName: Family
           },
           {
             Names: [
               "genus"
             ],
             ServerName: Genus
           },
           {
             Names: [
               "species"
             ],
             ServerName: Species
           },
           {
             Names: [
               "pet"
             ],
             ServerName: Pet
           },
           {
             Names: [
               "person"
             ],
             ServerName: Person
           }
         ],
         DatabaseTable: "breed",
         UniqueIds: [
           "id"
         ],
         DatabaseRelationships: [
           ["breed","id","person","id","pet_type","breed_id","pet_id","pet_ownership","animal_id","owner_id"],
           ["breed","id","pet","id","pet_type","breed_id","pet_id"],
           ["breed","species_id","species","id"],
           ["breed","species_id","genus","id","species","id","genus_id"],
           ["breed","species_id","family","id","species","id","genus_id","genus","id","family_id"]
         ]
       },
       {
         ServerName: Pet,
         Pseudonyms: [
           "pet",
           Pet
         ],
         ScalarFields: [
           {
             Name: "id",
             Type: Int,
             Arguments: []
           },
           {
             Name: "name",
             Type: Text,
             Arguments: []
           },
           {
             Name: "gender",
             Type: Int,
             Arguments: [
               {
                 Name: "as",
                 Options: [
                   {
                     Name: MALEFEMALE,
                     Type: Text,
                     Prefix: "CASE WHEN ",
                     Suffix: "==1 THEN MALE ELSE FEMALE END"
                   }
                 ]
               }
             ]
           }
         ],
         ObjectFields: [
           {
             Names: [
               "owner"
             ],
             ServerName: Person
           },
           {
             Names: [
               "breed"
             ],
             ServerName: Breed
           },
           {
             Names: [
               "species"
             ],
             ServerName: Species
           },
           {
             Names: [
               "genus"
             ],
             ServerName: Genus
           },
           {
             Names: [
               "family"
             ],
             ServerName: Family
           },
           {
             Names: [
               "taxonomy"
             ],
             ServerName: Taxonomy
           }
         ],
         DatabaseTable: "pet",
         UniqueIds: [
           "id"
         ],
         DatabaseRelationships: [
           ["pet","id","person","id","pet_ownership","animal_id","owner_id"],
           ["pet","id","breed","id","pet_type","pet_id","breed_id"],
           ["pet","id","species","id","pet_type","pet_id","breed_id","breed","id","species_id"],
           ["pet","id","genus","id","pet_type","pet_id","breed_id","breed","id","species_id","species","id","genus_id"],
           ["pet","id","family","id","pet_type","pet_id","breed_id","breed","id","species_id","species","id","genus_id","genus","id","family_id"]
         ]
       }
     ]
   }
  

Schema recommendation:

When you add every possible chain from every PrimitiveObject to every other PrimitiveObject, the schema coverage is extended.

Closing remark:

As the last remark, I'll turn attention to a quote from specifications.

"In contrast, GraphQL only returns the data that's explicitly requested, so new capabilities can be added via new types and new fields on those types without creating a breaking change. This has lead to a common practice of always avoiding breaking changes and serving a versionless API." - https://graphql.github.io/learn/best-practices/

With respect to that, you should elaborate on your schema representation. You should give all planned details, and you should make adjustments when you feel to evolve your server by making associations that are like simple arcs in a graph.

This function is to parse, validate, and interpret your query with variables. If you don't have variables, you may pass an empty string. The function is expecting your schema as SchemaSpec type from the above function. You can alternatively define you schema with lists and tuples.

You also can use the above function to print and paste your schema data into your script file.

Function return value:

The returned values are one tuple to contain information to pass into your database interface and to later reuse in below data processing function. The tuple is (PackagedObjects,SQLQueries). The second tuple member is a collection of queries. Examples are found in this repository page to pass queries (and data) to your database.

Function exceptions:

Exceptions are returned when error is faced. This method returns errors of:

• SyntaxException (if there is a problem with the given GraphQL query syntax)
• ParseFragmentException (if there is a problem with a Fragment syntax)
• EmptyQueryException (if the query is left blank)
• InvalidObjectException (if there is problem in nested object syntax, an object is not recognized, or server data is misinterpreted)
• InvalidObjectSubFieldException (if a subfield is requested from nested object that is not having ownership of the subfield)
• InvalidScalarException (if there is syntax error in listing scalar fields, or server data is misinterpreted)
• NullArgumentException (if a transformation is set but no argument is given though we do not yet support transformations)
• CreatingSqlQueryObjectFieldsException (if there are too many nested object subfields than nested objects to hold them or if there is a problem with the aligning of server object relationship argument - that's the fifth schema argument)
• RelationshipConfigurationException (if the relationship schema fifth arugment is incorrect number of String values, if an unrecognized pairing is found, or if two table field cardinalities are not same)
• FailedObjectEqualityException (if we could not match identical queries)
• DuplicateRootObjectsException (if there is an overlapping query)
• MissingVariableValueException (if we are missing variables in the variables-value string to the query)
• InvalidVariableNameException (if we cannot find a variable in the query with given variables-value string)
• MismatchedVariableTypeException (if query variable type is not matching object scalar type)
• InvalidVariableTypeException (if variable type is invalid or missing)
• ReadVariablesException (if the variables json string syntax is incorrect or was not correctly read)
• VariablesSyntaxException (if the query variables declaration is invalid syntax)

After casting all database results to Text (examples are given in this repository site), you may use this function to make GraphQL data.

The second argument is the package objects given from function processQueryString.

The return result is a string to resemble a GraphQL return value.

Formatting notes (IMPORTANT):

Nulls are expected as "Unexpected null". This is the Persistent default and important when processing ids to separate different results. One can translate nulls to "Unexpected null" when making Text types of query results. This is in the repository examples.

Function exceptions:

Exceptions are returned when error is faced. This method returns errors of:

• InvalidObjectException (when server data is misinterpreted or an unrecognized server object is met)
• InvalidScalarException (when server data is misinterpreted)
• EOFDataProcessingException (when the given data is shorter than expected in reference to the given serve objects)
• InvalidArgumentException (when there is an internal argument error - you should not observe this)
• InvalidVariableTypeException (when an unrecognized base data type is met)
• InvalidObjectScalarFieldException (when an unrecognized object-scalar pair is met)