AMI Script

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

All reserved types' values are immutable. Null is a valid value

Long	64 bit signed whole number
Double	64 bit signed float
String	Variable length string of UTF 8 characters
Integer	32 bit signed whole number
Float	32 bit signed float
Byte	8 bit signed whole number
Boolean	boolean (true or false)
Number	Base class for Long,Double,Integer,Float,Byte
UTC	Timestamp with millisecond precision (since unix epoch)

Examples

Integer i = 32;
Double d = 4.3, f = 132.d; //declaring multiple variables
Integer j = 0xaabcc;
String test = "hello world";
String Test = "Hello \
               world";     //Multi line 
Integer lng = 100000000000L;
Boolean flag = true;
Byte some_thing = null;

Casting

Variables are strongly typed, but casting can be explicit or implicit.  If a cast fails, the result evaluates to null. Also, equality operations (==, <=, >=, >, <, !=) will also auto cast when possible as well.

Examples

String test1 = 123;    //implicit cast from integer to string 
String test2 = "0x123";//implicit cast from hexidecimal integer to string 
Double val = "123.32"; //implicit case for string to double 
Boolean b = "true";    //implicit cast from string to boolean
String val = (Integer) 123.d; //explicit cast from double to integer, then implicit cast to String
Boolean c = "test";    //Evaluates to null because the implicit cast from string to boolean is invalid
Byte d;                //Evaluates to null by default

Variable Scoping

Scopes are defined using statement blocks, which are denoted by curly brackets: {…}. Within a statement block, variables are only visible after they are declared. When statement blocks are nested inside other statement blocks, all variables declared in the outer block are visible within the inner block as long as the variable is declared before the inner block. A variable cannot be re-declared when another variable with the same name is visible.

Examples

{
  Byte a;
  //a is visible;
  Byte b;
  //a & b are visible; 
  {
    Byte c;
    //a, b & c are visible;
    Byte d;
    //a, b, c & d are visible;
    {
      Byte e;
      //a, b, c, d & e are visible;
    }
    //a, b, c & d are visible;   
  }
  //a & b are visible;
  Byte a; //Compiler error: a already exists and can not be redefined
}

Standard Operators (in order of significance)

math_expressions

(evaluates to num_var type)

num_expr	*	num_expr	multiplication
num_expr	/	num_expr	division
num_expr	%	num_expr	modulus (remainder)
num_expr	+	num_expr	addition for numbers
num_expr	-	num_expr	subtraction

binary_expressions

(evaluates to num_int_expr type)

int_expr	~	int_expr	bitwise NOT
int_expr	<<	int_expr	signed bit shift left
int_expr	>>	int_expr	signed bit shift right
int_expr	>>>	int_expr	unsigned bit shift right
int_expr	&	int_expr	bitwise AND
int_expr	^	int_expr	bitwise XOR
int_expr	!	int_expr	bitwise OR

boolean_expressions

(evaluates to boolean)

	!	bool_expr	Example
expr	Example	Example	Example
expr	Example	Example	Example
expr	Example	Example	Example
expr	Example	Example	Example
expr	Example	Example	Example
expr	Example	Example	Example
expr	Example	Example	Example
expr	Example	Example	Example
expr	Example	Example	Example
expr	Example	Example	Example
expr	Example	Example	Example
expr	Example	Example	Example