Skip to content

JsonAdqlBuilder object description

Jump to bottom
galyfray edited this page Sep 23, 2021 · 9 revisions

Disclaimer

Under any circumstances no fields of this object should be directly acceded. This object is meant to be use only by the API and Connector parts and not by any external scripts. This page is parts of the internal documentation of the Tap Complex code.

General information

The JsonAdqlBuilder object aims to store and process data about adql constraints and joints relation between tables. All of these data and methods use the root table, defined in the object map, as a base referential . This means that all data about joints will be created by seeing the database structure through the tree view of the object map.

All methods will return an object like {"status":true|false "error": {}...} where the status field describe if the call is successful or not, the error field is only present if status is false and is an object described later in this page.

Internal data storage structure

The field joints store all known joints extracted from the object map, activeJoints store the name of all active and needed joints ensuring no table is joint twice and any level joints has all of their required joint added.

{
    "rootTable" : "table_Root",
    "scheme" : "'public'",

    "joints" : {
        "table_1" : {
          "from" : "table_1_key",
          "target" : "table_Root_key",
          "parentNode" : "table_Root"
        },
        "table_2" : {
            "from" : "table_2_key",
            "target" : "table_Root_key",
            "parentNode" : "table_Root"
        },
        "table_3" : {
            "from" : "table_3_key",
            "target" : "table_2_key",
            "parentNode" : "table_2"
        }
    },

    "nodeTreeBranches":{
        "table_2":[
            "table_3"
        ]
    },

    "conditions":{
        "table_3" : "adql valid condition for table 3"
    },

    "activeJoints" : [
        "table_2",
        "table_3"
    ]

 }

Methods specification

Constraints management

setTableConstraint

  • params :
    • table:String; unqualified name of the constraint table
    • constraint:String; valid adql constraint only constraining table, without any starting or leading adql keyword (WHERE,OR,AND, ...)
  • return :
    • {"status": true|false, "error?" : {}}

setTableContraints

  • info : this method builds and set multiple constraints for a single table.
  • params :
    • table:String; unqualified name of the constraint table
    • constraints:Array[String]; an array valid adql constraint only constraining table, without any starting or leading adql keyword (WHERE,OR,AND, ...)
    • logic:Array[String]; Optional an array of valid adql binary boolean operator (AND,OR) to be use to merge the constraints. If logic is too small and strict is either undefined or false no error is raised and the array gets looped to fill the missing blank.
    • strict:boolean Optional define if logic should exactly have the correct size according to logic's size
  • return :
    • {"status": true|false, "error?" : {},"constraint?" : "The constraint built and set"}

removeTableConstraints

  • info : remove any constraints on the table table
  • params :
    • table:String; unqualified name of the table
  • return :
    • {"status": true|false, "error?" : {}}

ADQL request building helpers

getAdqlJoints

  • info : create a string containing all active ADQL joints from the starting node ignoring any joints on same or higher level other nodes
  • params :
    • table:String; Optional unqualified name of the node table or the root table if unspecified
  • return :
    • {"status": true|false, "error?" : {},"adqlJoints?":"adql active joints"}

getAdqlConstraints

  • info : create a string containing all active ADQL constraints from the starting node ignoring any joints on same or higher level other nodes
  • params :
    • table:String; Optional unqualified name of the node table or the root table if unspecified
    • joinKeyVal:String; Optional, specific value of the key used to join table to his parentNode. This value is used to create an additional constraint and ignore if table is either undefined or the rootTable .
  • return :
    • {"status": true|false, "error?" : {},"adqlConstraints?":"adql active constraints"}

Other useful getters

getJoinKeys

  • info : return a set containing all fields which are use as join keys on/by the selected table
  • params :
    • table:String; unqualified name of the node table or the root table if unspecified
  • return :
    • {"status": true|false, "error?" : {},"keys?":["keys","set"]}

isTableJoined

  • info : check if the selected table is actively joint
  • params :
    • table:String; unqualified name of the node table
  • return :
    • {"status": true|false, "error?" : {},"joined?":true|false}

getTableConstraint

  • info : return the constraint put on the selected table or an empty string if no constraint is set
  • params :
    • table:String; unqualified name of the node table
  • return :
    • {"status": true|false, "error?" : {},"constraint?":""}

getSubTables

  • info : create a list of all tables which are deeper than the selected rootTable in the objectMap's tree representation of the DB
  • params :
    • table:String; Optional, unqualified name of the node table or the root table if unspecified
    • degree:int; Optional, degree of deepness allowed. Number.MAX_VALUE if unspecified.
  • return :
    • {"status": true|false, "error?" : {},"subTables?":"set of all known sub tables"}

getLowerJoints

  • info : Search and return all direct joint from the selected table to another. Only joints which goes deeper une the tree representation are returned ie table 1 is joined to the root and to table 2 and 3 then this method will only return joints to table 2 and 3. Joints are described following the same pattern as in the JsonAdqlBuilder specs
  • params :
    • table:String; Table from which joined table are searched
  • return :
    • {"status": true|false, "error?" : {},"joints?":"dictionary of all found joints"}

Error Object

The error object's main goal is to contain as much information as possible in order to be able to understand and handle the error. Internal errors are error raised by Tap Complex like "No active Tap connection". JavaScript errors are raised by JavaScript it can be a bug or an unhandled wrong parameter. parameters contain a copy of all parameters received by the function log contain addition data like error message or stacktraces in case of JavaScript errors.

{
    "params" : {"pram1":"val1"},
    "logs" : ""
}
Clone this wiki locally