Reference > AmiScript

AmiScript¶

AmiScript is AMI's embedded scripting language, combining procedural programming, embedded SQL, and string templating in a single unified language.

Overview¶

AmiScript compiles expressions before execution, enabling type checking and method resolution at compile time rather than at runtime. The language runs in two environments: the Web, where it powers UI callbacks and session logic, and the Center, where it drives datamodel triggers and stored procedures. See AmiScript Language Reference for a full explanation of how the language works.

The following example shows the language performing a cross-database join:

{
  //Inspect the ACCOUNTS table of two pre-defined databases (qadb & proddb).
  //Two temporary in-memory tables are created (qatemp and prtemp)
  String table = "ACCOUNTS";
  CREATE TABLE qatemp AS USE datasource=qadb   EXECUTE SELECT * FROM ${table};
  CREATE TABLE prtemp AS USE datasource=proddb EXECUTE SELECT * FROM ${table};

  //Gather some statistics, Note that the results of the queries on the in-memory tables are
  //stuffed into the local variables
  int qaCnt = select count(*) from qatemp;
  int prCnt = select count(*) from prtemp;
  int bothCnt = select count(*) from qatemp, prtemp where qatemp.id == prtemp.id;

  //Alert the user with some statistics, including the number of users in both qa and prod
  session.alert("Found ${qaCnt + prCnt} ${table} rows: ${qaCnt} in qa and ${prCnt} in prod. \
                 There are ${bothCnt} ids existing in both");

  //Create a Temporary ProdOnly table that contains all users in prod but not qa.
  //This table can be used in the visualization layer
  Create table ProdOnly as select * from prtemp where !(id in (select id from qatemp));
}

Note the interoperability of SQL and procedural style language as well as the dynamic string notation functionality (encased like so ${...}).

Execution Contexts¶

AmiScript can be invoked from several contexts within AMI.

Context	Description
Datamodel triggers	Scripts attached to a datamodel that fire on data events: `onInsert`, `onUpdate`, `onDelete`, and `onStartup`.
UI callbacks	Scripts bound to user interactions such as button clicks, cell selection, and panel events.
Stored procedures	Named scripts invoked by name from other scripts or scheduled processes.
Timers	Scripts executed on a defined schedule by the Center.
Shell tool	Scripts executed directly via the AMI shell for testing and administration.

Language Components¶

Scripting Language¶

AmiScript is a versatile language designed for optimized on-the-fly compilation, meaning expressions can be re-compiled and evaluated in an instant.

Type Safe: All variables have well-defined types, e.g: String, Integer, etc.
Compile Time Binding: Expressions are compiled and type-checked before execution, minimizing runtime issues.
Procedural: Supports custom methods with overloading and a set of predefined procedures.
Object Oriented: AMI objects are accessible and manipulable directly in AmiScript.
Event Driven: Executes in response to events such as datamodel updates and UI interactions.
Implicit Casting: Types can be cast explicitly or implicitly.
Embedded SQL: Provides direct access to external datasources and in-memory tables.
String Templating: Supports dynamic text generation through template syntax.
Task Swapping: Supports out-of-band execution on a separate thread.

Embedded SQL¶

An SQL-style language extension to AmiScript with near-full SQL support and several enhancements geared towards data preparation for the visualization of data. All functions act on an in-memory database, with support for calling out to external datasources.

Retrieval: Accessing and normalizing data from external sources.
Blending: Joining and unioning tables.
Modifying: Inserting, updating, and deleting rows.
Analyzing: Grouping, sorting, and filtering.
Schema Definition: Creating, updating, and dropping tables.

String Templating¶

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

Embed AmiScript:
- Inside text: Embedding AmiScript inside text allows for easy dynamic text generation.
- Inside SQL: Embedding AmiScript inside SQL allows for easy dynamic SQL generation.
Injection Protection: Properly escaping control characters, quotes, etc.
Conditional Templating: Ability to do conditional and loop-based template construction.