Difference between revisions of "AMI Script"

From 3forge Documentation
Jump to navigation Jump to search
Tag: visualeditor-switched
Tag: visualeditor-switched
Line 65: Line 65:
  
 
===Literals (Constants)===
 
===Literals (Constants)===
 +
{| class="wikitable"
 +
|<span style="font-family: courier new; color: blue;">digits</span>
 +
|Int constant
 +
|-
 +
|<span style="font-family: courier new; color: red;">0x</span><span style="font-family: courier new; color: blue;">digits</span>
 +
|Hex Int constant
 +
|-
 +
|<span style="font-family: courier new; color: red;">0</span><span style="font-family: courier new; color: blue;">digits</span>
 +
|Octal Int constant
 +
|-
 +
|<span style="font-family: courier new; color: blue;">digits</span><span style="font-family: courier new; color: red;">L</span>
 +
|Long constant
 +
|-
 +
|<span style="font-family: courier new; color: red;">0x</span><span style="font-family: courier new; color: blue;">digits</span><span style="font-family: courier new; color: red;">L</span>
 +
|Hex long constant
 +
|-
 +
|<span style="font-family: courier new; color: red;">0</span><span style="font-family: courier new; color: blue;">digits</span><span style="font-family: courier new; color: red;">L</span>
 +
|Octal long constant
 +
|-
 +
|<span style="font-family: courier new; color: blue;">digits.digits</span>
 +
|Float constant.  Note, scientific (aka 'E') notation is supported
 +
|-
 +
|<span style="font-family: courier new; color: blue;">digits.digitsD</span>
 +
|Double constant.  Note, scientific (aka 'E') notation is supported
 +
|-
 +
|<span style="font-family: courier new; color: red;">"</span><span style="font-family: courier new; color: blue;">chars</span><span style="font-family: courier new; color: red;">"</span>
 +
|String constant.  Use backslash (\) to escape quotes, backslash (\\)   and other control chars, ex: \n. A string can be defined over multiple lines using a trailing backslash on all but the last line, note that preceding white space is trimmed out for subsequent lines. Please see String Templating section for  details on ${…} syntax
 +
|-
 +
|<span style="font-family: courier new; color: red;">\n\r\t<space></span>
 +
|White space (token delimiter)
 +
|}
  
 
===Reserved Type===
 
===Reserved Type===

Revision as of 00:15, 24 March 2021

AMI Script Introduction

Overview

AMI has an embedded, versatile language which is a combination of the well-known C/Java style, SQL and String Templating languages.  Here is a very quick example of the incredible versatility of the language which does a cross-database join:

 1{
 2  //Inspect the ACCOUNTS table of two pre-defined databases (qadb & proddb).
 3  //Two temporary in-memory tables are created (qatemp and prtemp)
 4  String table = "ACCOUNTS";
 5  CREATE TABLE qatemp AS USE datasource=qadb   EXECUTE SELECT * FROM ${table};
 6  CREATE TABLE prtemp AS USE datasource=proddb EXECUTE SELECT * FROM ${table};
 7
 8  //Gather some statistics, Note that the results of the queries on the in-memory tables are
 9  //stuffed into the local variables
10  int qaCnt = select count(*) from qatemp;
11  int prCnt = select count(*) from prtemp;
12  int bothCnt = select count(*) from qatemp, prtemp where qatemp.id == prtemp.id;
13
14  //Alert the user with some statistics, including the number of users in both qa and prod
15  session.alert("Found ${qaCnt + prCnt} ${table} rows: ${qaCnt} in qa and ${prCnt} in prod. \
16                 There are ${bothCnt} ids existing in both");
17
18  //Create a Temporary ProdOnly table that contains all users in prod but not qa.
19  //This table can be used in the visualization layer
20  Create table ProdOnly as select * from prtemp where !(id in (select id from qatemp));
21}

In this introductory language you can see the interoperability of SQL and a procedural style language. The ${...} syntax is used for easily creating dynamic strings and SQL statements.

Key Features

AMI Script is a versatile language designed for optimized "on the fly" compilation, meaning expressions can be re-compiled and evaluated in an instant.  Some key features of the language:

  • Type Safe - All variables have well defined types, ex: String vs. Integer
  • Compile Time Binding - Code is compiled before execution to minimize runtime issues
  • Procedural -  Custom methods (with overloading), along with a set of predefined procedures
  • Object Oriented - Objects in AMI are represented as such in Ami Script
  • Event Driven - Executes based on events, such as running a datamodel or clicking a button
  • Implicit Casting - Casting from one type to another can be explicitly or implicitly defined
  • Embedded SQL - For accessing external sources and tables directly in the language. See below
  • String Templating - Ability to template code for reuse. See below
  • Task Swapping - Tasks can be exported runtime for out-of-band execution. (separate thread)

Embedded SQL is an SQL-style language extension to AMI Script with near-full SQL support along with several enhancements geared towards data preparation for the visualization of data.  All of these functions act on an in-memory database. It also supports "calling out" to external datasources. Some key features are:

  • Query Clauses - For filtering, joining, and grouping data on the in-memory database
  • Data Modification - For adding, updating, and deleting data on the in-memory database
  • Schema Modification - For adding, editing, and deleting tables/columns on the in-memory database
  • Use … Execute - For seamlessly running code on external datasources and storing results to the in-memory database
  • Advanced Data Preparation and Analysis - For complex data calculations, not typically available on a standard SQL database
  • Lambda Support -The ability to run AMI script code inside SQL. For example, to run a code snippet per row returned in a table
  • Nested Queries - The in(…) clause supports full nested queries, and also supports multiple column in-clauses
  • Intelligent Indexing - As joins, in-clauses, etc. are evaluated, indexes will automatically be spun up depending on data size and cardinality

AMI Script Template syntax is an extension of AMI Script with the aim of simplifying dynamic text generation, useful for creating dynamic HTML, dynamic SQL, etc.

  • Embed Ami Script inside Text - Embed AMI script inside text allows for easy dynamic text generation
  • Embed Ami Script inside SQL - Embed AMI script inside SQL allows for easy dynamic SQL generation
  • Injection Protection - Properly escaping control characters, quotes, etc.
  • Conditional Templating - Ability to do conditional & loop based template construction

AMI Script

Variable Naming

Case-sensitive combination of a-z, A-Z, _, 0-9.  The first character must not be a number. Alternatively, variables can be wrapped in back ticks (`), in which case all characters are supported, allowing for accessibility with external language references.  Note: `test` is equivalent to test. Variables are declared with the following syntax (the value will default to null if an expression is not supplied):

type variable_name [ = expression][, variable_name [ = expression] ... ];

Literals (Constants)

digits Int constant
0xdigits Hex Int constant
0digits Octal Int constant
digitsL Long constant
0xdigitsL Hex long constant
0digitsL Octal long constant
digits.digits Float constant.  Note, scientific (aka 'E') notation is supported
digits.digitsD Double constant.  Note, scientific (aka 'E') notation is supported
"chars" String constant.  Use backslash (\) to escape quotes, backslash (\\)   and other control chars, ex: \n. A string can be defined over multiple lines using a trailing backslash on all but the last line, note that preceding white space is trimmed out for subsequent lines. Please see String Templating section for  details on ${…} syntax
\n\r\t<space> White space (token delimiter)

Reserved Type