This function is to parse your schema. The return value is 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. You also may run this function once and declare the returned values before all the other function calls.

Schema:

The schema json file is formated as one json object to detail the GraphQL objects and the object heirarchy. Only PrimaryObjects are valid descendants to Interfaces. Only the shared object fields and shared scalar fields are interface fields. If a interface is a declared field from a primary object, all interface-interpreted objects are supposed to be declared in database relationships from the primary object with the object property field. When declaring any primary object or interface, the pseudonym is supposed to list all possible root object calling references. As a nested object, you should declare the object names in the nested object field definitions in object that's holding property of the object or interface in definition. Primary objects are expected to not have all NULL unique id values, and they are otherwise removed from the result when reading the data. 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 separately declares every field with a space " " separation between ids. 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 object associations as declaring more object-fields in the primary 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, Int64, Double, or Boolean (for JSON format).

Function exceptions:

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

• ReadSchemaFileException (I could not read file.)
• SchemaDuplicateServerObjectException (I found duplicate primary object.)
• SchemaDuplicateInterfaceException (I found duplicate interface server object.)
• ReadJsonObjectsException (I failed to a read list of json objects. Is it formatted correctly?)
• ReadServerNameStringException (ServerName is not read correctly.)
• ReadScalarFieldException (Scalar field is not read correctly.)
• ReadDatabaseTableException (Database table string is not read correctly.)
• ReadJsonStringException (String is not read correctly.)
• ReadPseudonymsException (Pseudonyms string list is not read correctly.)
• ReadInterfaceInstancesException (Interface instances string list is not read correctly.)
• ReadDatabaseIdsException (Database ids string list is not read correctly.)
• ReadJsonStringListException (String list is not read correctly.)
• ReadDatabaseRelationshipsException (Database relationships [[String]] is not read correctly.)
• ScalarFieldDataTypeException (Data type is not recognized.)
• ReadDatabaseRelationshipsCardinalityException (Tables cardinality is unexpected.)
• PrimaryObjectNotFoundException (Primary object is not found for interface.)
• SchemaDuplicateException (Duplicate in name, scalar, object fields, or relationships.)
• InterfaceScalarTypesException (Interface scalars are not same types for scalars of same name in interface interpretations.)

Schema format example:

This is the syntax for the schema file:

   {
     Interfaces:[
       ({
         ServerName:SERVEROBJECTNAME,
         Pseudonyms:[(String)+],
         ServerChildren:[(SERVEROBJECTNAME)+]
       })*
     ],
     PrimitiveObjects:[
       ({
         ServerName: SERVEROBJECTNAME,
         Pseudonyms: [(String)+],
         ScalarFields: [
           ({
             Name: String,
             Type: DATATYPE,
             Arguments: [
               ({
                 Name: String,
                 Options: [
                   ({
                     Name: String,
                     Type: TYPE,
                     Prefix: String,
                     Suffix: String
                   })+
                 ]
               })*
             ]
           })*
         ],
         ObjectFields: [
           ({
             Names: [String],
             ServerName: SERVEROBJECTNAME
           })*
         ],
         DatabaseTable: String,
         UniqueIds: [String],
         DatabaseRelationships: [
           ([FROMTABLE,FROMJOINIDS,TOTABLE,TOJOINIDS(,NEXTTABLEBYFROMTABLE,NEXTABLEENTRYIDS,NEXTTABLEEXITIDS)*])*
         ]
       })+
     ]
   }

   SERVEROBJECTNAME = String
   TYPE = Text | Int64 | Double | Boolean
   FROMTABLE = String
   FROMJOINIDS = String
   TOTABLE = String
   TOJOINIDS = String
   NEXTTABLEBYFROMTABLE = String
   NEXTABLEENTRYIDS = String
   NEXTTABLEEXITIDS = String
  

You may find an example in the repo. You should have a database relationship for every object field and every interface interpreted field in a primary object.

Schema recommendation:

When you add every PrimaryObject as a field to every PrimaryObject, the schema coverage is extended.

Closing remark:

As the last remark, I will 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 make adjustments when you feel to evolve your server with new associations like simple arcs in a graph.

These two functions are to parse, validate, and interpret your GraphQL 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 by calling the above function once and declaring the output as the SchemaSpec argument for this function, so you do not repeatedly parse the json schema file.

_Function return value:__

The returned values are one tuple to contain query information to later pass to the data processing function. The tuple is (QueryData,SQLQueries). The second tuple member is a collection of queries to iterate and give to your database. Examples are found in this repository page.

Function exceptions:

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

• MissingVariableValueException (No value is found for query variable(s).)
• ReadVariablesJsonException (Variables JSON string is not read correctly.)
• VariablesSyntaxException (Query syntax error in variables section.)
• InvalidVariableTypeException (Variable type is not Text, Int64, Double, nor Boolean.)
• EmptyQueryException (Query is not found.)
• ParseFragmentException (I found an unexpected character when reading a fragment, imbalanced brackets, or missing syntax.)
• InvalidObjectException (I found syntax error when reading object in query.)
• FindFragmentException (I cannot find fragment in given for query.)
• ReadDirectiveException (I cannot read directive and value combination.)
• MismatchedVariableTypeException (Given variable is not same type as expected input.)
• InvalidVariableNameException (Variable is not found by name.)
• InvalidScalarException (Scalar field declaration is unexpected structure.)
• TransformationSyntaxException (Transformation is not read correctly.)
• RelationshipCardinalityException (I found unexpected tables count in database relationship declaration.)
• RelationshipLinkageIdException (Columns cardinality is different between tables that are linked in join.)
• UnrecognisedObjectException (Object/Interface is not found in schema; interface object field is not found in schema)
• UnrecognisedArgumentException (Argument is not found for object scalar field in schema.)
• UnrecognisedOptionException (Argument option is not found for object scalar field argument (in schema).)
• UnrecognisedScalarException (Scalar is not found in schema.)
• DisagreeingObjectFieldsException (Object fields in interface are different server objects.)
• UnrecognisedRelationshipException (Server object database relationship is not found.)
• DuplicateObjectsException (multiple objects are sharing same alias, but their subselections are different.)
• QuerySyntaxException (query syntax is invalid)
• InvalidPropertiesException (object fields are invalid)

Not all databases are providing support for json aggregation in sql queries, so you may use the above function for those cases. This function is returning queries with json aggregation to format output in the database. It is faster.

These two functions are for processing database query results to GraphQL style. You must correspond the respective function to the function from the above two in your application.

The first four arguments are function to translate your database value types to the declared type for the field. Examples are found in repo,

The fifth argument is a function to check if the database returned value is a null. This is for checking existence of values present.

The seventh argument is the query data from processQueryString or processAggQueryString.

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

Function exceptions:

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

• InvalidVariableTypeException (Variable type is not Text, Int64, Double, nor Boolean.)
• ReadJsonException (Could not read json from database)

This function is for processAggQueryString correspondence.