ArcGIS REST API

Reading and Writing Layers in pyspark

The Run Python Script task allows you to programmatically access and use ArcGIS Enterprise layers with both GeoAnalytics Tools and the pyspark package. Reading and writing ArcGIS Enterprise layers is described below with several examples. For more examples, see Examples: Scripting custom analysis with the Run Python Script task.

Reading Layers

Run Python Script allows you to read in input layers for analysis. When you read in a layer, ArcGIS Enterprise layers must be converted to Spark DataFrames to be used by geoanalytics or pyspark functions. DataFrames have built in operations that allow you to query your data, apply filters, change the schema, and more. For more information see Spark's guide to DataFrame operations. There are two ways to convert layers to DataFrames:

  • Using the layers object —Layers listed in the inputLayers parameter of the Run Python Script task are automatically loaded into DataFrames when you run a script. These DataFrames are contained in a layers object . layers is a list of DataFrames where the index of each DataFrame matches the index of the corresponding layer in the JSON array provided for inputLayers.
  • Using a URL within the script—Layers can be loaded into DataFrames within the script by calling spark.read.format("webgis").load(<URL>) using the URL to a feature service or big data file share layer.

When a layer is converted to a DataFrame, the layer's geometry will be included in the DataFrame in a column called $geometry. If a layer is time enabled, the time will be included in a column called $time.

In the example script below, multiple input layers of crime events have been defined with the inputLayers parameter. These layers are all accessible as DataFrames within the script and can be queried using DataFrame operations. Here, the total count of burglaries across several datasets is found and printed out.

Accessing multiple input layers in the Run Python Script task with the layers object.

# Report the number of input layers that were provided
print("{0} input layers have been defined".format(len(layers)))

# Iterate through each layer and find the total count of features where "type" is equal to "BURGLARY"
count_burglaries = 0

for layer in layers:
     count_burglaries += layer.filter(layer["Type"] == "BURGLARY").count()

print("Total number of burglaries in all input layers: " + str(count_burglaries))

In this example a DataFrame is created using the URL of a big data file share layer containing sensor data. The DataFrame is then used to print the sensor ID of all features with a sample measurement value greater than 500.

Accessing ArcGIS Enterprise layers in the Run Python Script task with a layer URL.

sensor_data = "https://host.domain.com/arcgis/rest/DataStoreCatalogs/bigDataFileShares_OzoneData/BigDataCatalogServer/samples_2017"

# Load the big data file share layer into a DataFrame
sensor_data_df = spark.read.format("webgis").load(sensor_data)

# Show all features where the value of field "sample_measurement" is greater than 500
sensor_data_df.filter(sensor_data_df["sample_measurement"] > 500).select("sensor_ID").show()

Filtering and extent

You can choose to filter a layer while converting it to a DataFrame using the option method. This allows you to read in only a subset of your data, reducing the runtime of your analysis. The "where" option can be used to filter the layer with an SQL query by calling spark.read.format("webgis").option("where", <SQL query string>).load(<URL>). You can also use the "fields" option to choose which fields are loaded into the DataFrame by calling spark.read.format("webgis").option("fields", <field names>).load(<URL>).

In this example a DataFrame is created using the URL of a big data file share layer containing sensor data. The "where" and "fields" options are used to filter the layer and specify which fields should be included in the result DataFrame.

Filtering an ArcGIS Enterprise layer when creating a DataFrame.

sensor_data = "https://host.domain.com/arcgis/rest/DataStoreCatalogs/bigDataFileShares_OzoneData/BigDataCatalogServer/samples_2017"

# Load the big data file share layer into a DataFrame
sensor_data_df = spark.read.format("webgis").option("where", "sample_measurement > 500").option("fields", "Site Num,sample_measurment")load(sensor_data)

The "extent" option can be used to filter a layer spatially by calling spark.read.format("webgis").option("extent", <extent string>).load(<URL>).

In this example a DataFrame is created using the URL of a feature service layer. The "extent" option is used to only read in features within the extent specified.

Setting the extent of an ArcGIS Enterprise layer when creating a DataFrame.

input_data = "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/Congressional_District_Demographics/FeatureServer/0"

# Define extent
extent_str =  "{\"xmin\":-11535264.81,\"ymin\":1271271.06,\"xmax\":-5606197.40,\"ymax\":7337313.62,\"spatialReference\":{\"wkid\":102100}}"

# Load the feature service layer into a DataFrame using the extent
input_df = spark.read.format("webgis").option("extent", extent_str).load(input_data)

Writing Layers

There are three different ways you can write results:

  • Write as feature layers in your ArcGIS Enterprise portal
  • Write to a big data file shares using templates
  • Write to data formats supported by spark

DataFrames are only held in memory during the runtime of your Python script. To save any result to ArcGIS Enterprise you must call write.format("webgis").save(<output name>) on the DataFrame. The name of the output feature service is be specified by <output name>.

In this example, a Living Atlas layer is copied to the ArcGIS Data Store of type spatiotemporal (the spatiotemporal big data store).

Writing a DataFrame to the spatiotemporal big data store.

# Load the Living Atlas layer into a DataFrame
url = "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/USA_HistoricSites_2016/FeatureServer/0"
USA_HistoricSites = spark.read.format("webgis").load(url)

# Write the DataFrame to the spatiotemporal big data store
USA_HistoricSites.write.format("webgis").save("USA_HistoricSites_copy")

All layers will be written to the spatiotemporal big data store by default unless you use the option method with the "dataStore" option to specify a different data store. You can do this by calling write.format("webgis").option("dataStore",<data store>).save(<output name>).

In this example, a Living Atlas layer is copied to a big data file share called "OutputBDFS" using an output template called "shp_default"

Writing a DataFrame to a big data file share.

# Load the Living Atlas layer into a DataFrame
url = "https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/USA_HistoricSites_2016/FeatureServer/0"
USA_HistoricSites = spark.read.format("webgis").load(url)

# Write the DataFrame to a big data file share using an output template called "shp_default"
USA_HistoricSites.write.format("webgis").option("dataStore":"/bigDataFileShares/OutputBDFS:shp_default").save("USA_HistoricSites_copy")

Only layers written with format("webgis") will be available in ArcGIS Enterprise. To learn about writing to output formats other than ArcGIS Enterprise layers, see Spark's documentation for write(). In the example below, a list of customers who meet a certain criteria is generated and written to a shared folder that the ArcGIS Server account has write access to. The result will not be available in ArcGIS Enterprise and may be written in multiple parts. The number of parts is dependent on how Spark has distributed the computation.

Writing a file external to ArcGIS Enterprise.

# Load a big data file share layer of customers into a DataFrame
url = "https://host.domain.com/arcgis/rest/DataStoreCatalogs/bigDataFileShares_CustomerData/BigDataCatalogServer/active_time"
customers = spark.read.format("webgis").load(url)

# Find all customers who have been logged into an application for more than 300 minutes per week
IDs = customers.filter(customers["weekly_time_active"] > 300).select("ID")

# Write the result to a shared folder in JSON format
out_path = "\\\\data\\active_customerids"
IDs.write.format("json").save(out_path)