Frequently Asked Questions

Why Arcade?

You may find yourself asking, "Why did Esri bother writing its own language when it probably could have used others, like Python?"

This decision was made because we needed an expression language that met the following requirements:

  • Lightweight and simple - A language with a small number of functions and an easy syntax.
  • Portable - A language that can execute in multiple environments with the same syntax for web, desktop, and mobile apps.
  • Secure - A language that doesn't have security vulnerabilities that open the door to malicious scripts.
  • Geospatial first - A language that makes geospatial functions and capabilities first-class citizens.

Developing our own scripting language was the best option because other alternatives, such as Python and JavaScript, couldn't check all of the boxes above either due to language size, or their propensities for security issues.

Arcade is secure because it cannot be injected with executable code outside of its intended context. It is also portable and sharable; expressions can be authored in an app using one ArcGIS API, and understood by another without syntax differences. That means you can author an expression for labeling features in ArcGIS Online and that same expression will render labels the same way in ArcGIS Pro, the ArcGIS API for JavaScript, or any of the Runtime APIs. Another benefit of Arcade is extensibility. The team at Esri can add functions specific to GIS applications, such as geometry calculations, to Arcade’s function library as use cases and demand drive the need for them.

Where can I use Arcade?

Arcade is an expression language intended for use solely within the ArcGIS platform. It is not a standalone language intended for building apps or for executing expressions within other apps not supported by ArcGIS. It can only be executed within the context of a designated profiles, such as labeling, visualization, popups, calculation, and constraints.

For example, Arcade can be used to calculate values client-side for the popup.

// displays the % change between two attributes for the popup
var pop2020 = $feature.POP_2020;
var pop2010 = $feature.POP_2010;
var perChange = ( ( pop2020 - pop2010 ) / pop2010 );
// implicitly casts the number as a string
return Round( perChange ) + "%";

See the Getting started with Arcade page and other guide pages to learn more about when you can use Arcade.

Which version of Arcade does my product or API use?

You can use the version matrix to find the Arcade version corresponding to the ArcGIS product you're using. See the release notes to view the features new to each release. The documentation of each function also indicates the Arcade version in which the function was added. If no version is specified, then the function was added in the initial 1.0 release of Arcade.

Can Arcade be used to build standalone apps?

No. It is an expression language intended for evaluating the values of attribute fields and geometries within the context of apps authored by another ArcGIS product, such as ArcGIS Pro, ArcGIS Online, or the ArcGIS API for JavaScript.

How do I control the execution of Arcade?

Currently, you cannot execute Arcade expressions outside of a supported execution profile. If you have a use case for creating your own Arcade execution profile, then please send us feedback and describe in detail what you are trying to accomplish and how Arcade can help you.

How do I create my own Arcade profiles?

We currently don't document a way to create your own Arcade profiles. If you have a need for new Arcade profiles (or environments for executing Arcade), then please send us feedback and describe in detail what you are trying to accomplish and how a new Arcade profile can help you.

What is the $ character used for?

The dollar sign $ character prefixes all valid global variables in an Arcade profile. All profiles support the $feature global, and some include the $view.scale global. $feature represents the feature currently executing the Arcade expression. You can reference attributes in the feature by using the $feature.FieldName syntax and get its geometry using any geometry function.

// $feature gives you access to field values
// so you can use them in calculations
$feature.POPULATION / $feature.SQ_MILES;

// Assume the $feature is a point geometry
var featureGeometry = Geometry($feature);

// returns the x-coordinate of the geometry

Can I use Arcade outside the ArcGIS platform?

No. Arcade may only be executed in a supported Arcade profile.

Where can I use geometry functions?

You can use geometry functions in any execution profile. However, you should be aware that since Arcade expressions execute for each feature, using multiple geometry operations within the context of some profiles, such as labeling and visualization, can be expensive and severely impact the performance of the application. Therefore, it may be more advisable to reserve certain geometry operations for other cases, such as the popup profile.

Can I use any function in any profile?

The majority of functions may be used in any profile, but not all functions are designed for all profiles.

Some functions are reserved for specific profile(s). The documentation for each function indicates the valid profiles where it may be used. If a target profile is not specified in the documentation, then you can assume that the function may be used in any profile.

How do I work with null values in popups?

There are several different ways to handle null values in your data. A common workflow is to replace an awkward blank spot in your popup with a coherent phrase or default placeholder. The IsEmpty() and DefaultValue() functions can conveniently help you handle these situations.

How do I reference data from a joined table?

Map services allow you to create dynamic table joins. Arcade can reference data in a joined table within a map service using the square bracket notation for field names: $feature["tableName.fieldName"].

// Election data for 2016 in one table named "election2016"
// Election data for 2012 in another table named "election2012"
var demVotes2016 = $feature["election2016.VOTED_DEM"];
var demVotes2012 = $feature["election2012.VOTED_DEM"];

// returns % change in votes from 2012 to 2016
Round( ( ( demVotes2016 - demVotes2012 ) / demVotes2012 ) * 100, 2);

This example in the ArcGIS API for JavaScript demonstrates how this works.

You can access data from related tables using FeatureSet functions.

Can I access data from other layers, web maps, or data sources?

Yes. You can access data from other layers using the FeatureSet functions in profiles that support them.

Where can I find examples of Arcade used in web apps?

You can find examples in the following places:

Where can I share my Arcade expressions with others?

You can publicly share Arcade expression templates with others in the Esri/arcade-expressions GitHub repository. This repository is intended for sharing and maintaining reuseable Arcade expressions across all supported profiles.

Can I use an Arcade expression outside script tags in a web app?

Yes. JavaScript treats Arcade expressions as string values, so you can write simple, one-line expressions as a string within a JavaScript file. You can also write and reference Arcade expressions in separate text files. Furthermore, you can use JavaScript to generate Arcade expressions dynamically in a web app. See the MapImageLayer - Explore data from a dynamic workspace sample for an example of this.

Why doesn't my expression work in my web app, but it does in ArcGIS Online?

Arcade expressions are portable as along as the functions used in the expression and the execution profile are supported in the versions of Arcade used by the apps sharing the same expression.

For example, you can create an Arcade expression for a popup in ArcGIS Online, which will always use the latest version of Arcade. However, the popup will not recognize the same expression if the web map or layer is loaded in an app built with version 3.19 of the ArcGIS API for JavaScript because that version uses Arcade 1.0, which doesn't include popup support.

Another example is $feature casting to Geometry in geometry functions. In Arcade 1.4, the following expression is valid:

Area( $feature, "kilometers" )

But it is not valid in Arcade 1.3. Arcade 1.3 doesn't automatically cast a feature to a geometry, so you will need to cast the geometry yourself to ensure portability.

Area ( Geometry($feature), "kilometers" )

Also note that geometry functions weren't supported until Arcade 1.3, so neither of the expressions will work if you attempt to use them in an app that uses Arcade 1.2 or prior.

To ensure portability, you should try to use the latest version of Arcade as possible in each of your apps.

Can I work with two geometries that have different spatial references?

No. When working with multiple geometries using geometry functions, their spatial references must match. The spatial reference of all geometries must match the spatial reference of the map or service executing the expression as well.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.