Feature Service

A feature service is a data service that stores and hosts spatial and nonspatial data online. In a feature service, spatial datasets are feature layers and non-spatial datasets are tables. You can query, edit and analyze data in a feature service. Feature service URLs are typically in the formats shown below.

URL for a feature service layer or table hosted in ArcGIS Online: https://<host>/<uniqueID>/ArcGIS/rest/services/<serviceName>/FeatureServer/<Layer or Table ID>

URL for a feature service layer or table hosted in ArcGIS Enterprise: https://<host>/<webadaptor>/rest/services/Hosted/<serviceName>/FeatureServer/<Layer or Table ID>.

Refer to the feature service documentation for ArcGIS Online and ArcGIS Enterprise for more details.

Register a GIS

Authentication will be required when reading or saving a secured feature service hosted by ArcGIS Online or ArcGIS Enterprise. GeoAnalytics Engine supports authentication by registering a GIS (i.e. a connection to ArcGIS Online or ArcGIS Enterprise) with the register_gis function.

The default GIS in register_gis is ArcGIS Online and only a username and password are required in that case, as shown in the following example.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
import geoanalytics
geoanalytics.register_gis("myGIS", username="User", password="p@ssw0rd")

To connect to ArcGIS Enterprise, specify the portal URL along with a username and password, as shown in the following example. You can use credentials from the built-in identity store or from your Lightweight Directory Access Protocol (LDAP) server. Other authentication configurations are not supported. For more information see Portal authentication configuration.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
import geoanalytics
geoanalytics.register_gis("myPortal", "https://example.com/portal", username="User", password="p@ssw0rd")

To remove a GIS, use the unregister_gis function as shown in the following example.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
import geoanalytics
geoanalytics.unregister_gis("myGIS")

Each GIS name can only be registered once.

Read from feature services

GeoAnalytics Engine supports loading data from feature services into a Spark DataFrame for use with any operations supported on a DataFrame in GeoAnalytics Engine or PySpark.

The following example shows the Python syntax for loading a feature service into a Spark DataFrame, where URL is the URL to a feature service layer or table. URL is not required if specified using the DataFrameReader option listed in the table below.

1
spark.read.format("feature-service").option().load(URL)

Below is a table of options that GeoAnalytics Engine supports when loading a feature service with Spark DataFrameReader.

When loading a public feature service layer or table, you can pass the URL without options 'gis' or 'token':

1
spark.read.format("feature-service").load(URL)

When loading a secured feature service layer or table, a GIS connection or token will be required. For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
import geoanalytics
geoanalytics.register_gis("myGIS", username="User", password="p@ssw0rd")
spark.read.format("feature-service").options('gis', "myGIS").load(URL)

For more examples on how to load a feature service layer, refer to the Read from feature services tutorial.

Write to feature services

GeoAnalytics Engine extends Spark and supports saving data in feature services. You can serve and share feature services over the internet. You can also access, visualize, or edit the published feature services in an ArcGIS Online or Enterprise portal.

The following script shows the Python syntax of saving feature services that GeoAnalytics Engine currently supports:

1
df.write.format("feature-service").option().save()

Below is a table of options and modes that GeoAnalytics Engine supports when saving a feature service with Spark DataFrameWriter. The default mode is to create a new feature service.

When saving a feature service, either a registered GIS or a token is required. Below is an example of registering a GIS and saving a feature service.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
import geoanalytics
geoanalytics.register_gis("myGIS", username="User", password="p@ssw0rd")

data = [
    ('{"x": -0.126,"y": 51.504,"m": 187.73}', 43.26),
    ('{"x": -0.126,"y": 51.504}', 97.22)
]
df = spark.createDataFrame(data, ["esri_json", "value"]) \
          .withColumn("point", ST.point_from_esri_json("esri_json"))

df.write.format("feature-service") \
        .option("gis", "myGIS") \
        .option("serviceName", "esri_json_output") \
        .save()

For more examples on how to save feature services, refer to the Write to feature services tutorial.

Usage notes

• A layer or table ID must be included in the feature service URL when loading.
• Secured feature services can be read by either providing a registered GIS or a token.
• When loading a feature service layer with geometries, the geometry field will be included in the result DataFrame automatically as as a point, multipoint, line, or polygon column.
• A registered GIS or a token and Portal URL are required when saving a feature service.
• When saving a Spark DataFrame with a geometry column, a feature layer will be created. For a Spark DataFrame without a geometry column, a table will be created in the new feature service. A spatial reference is required to be set on the geometry column when saving to a feature layer.
• The generic geometry type is not supported when saving a feature service. The geometry type should be one of the following types: point, multipoint, line, or polygon.
• The option layerId can only be used to overwrite or append to an existing layer. Use the layerName option when creating a new layer.
• The option serviceName should only be used when writing to a new feature service, and the service name needs to be unique within your ArcGIS Enterprise or ArcGIS Online organization. To overwrite or append to an existing layer, use serviceUrl.
• When providing serviceUrl, layerId, or layerName must also be specified.