ServiceFeatureTable Class

  • ServiceFeatureTable
  • class Esri::ArcGISRuntime::ServiceFeatureTable

    A table of features that typically represent real-world objects created from an ArcGIS feature service. More...

    Header: #include <ServiceFeatureTable.h>
    Since: Esri::ArcGISRuntime 100.0
    Inherits: Esri::ArcGISRuntime::ArcGISFeatureTable, Esri::ArcGISRuntime::ApiKeyResource, and Esri::ArcGISRuntime::RemoteResource

    Public Functions

    ServiceFeatureTable(const QUrl &url, QObject *parent = nullptr)
    ServiceFeatureTable(Esri::ArcGISRuntime::ServiceFeatureTable *table, const Esri::ArcGISRuntime::RelationshipInfo &relationshipInfo, QObject *parent = nullptr)
    ServiceFeatureTable(const QUrl &url, Esri::ArcGISRuntime::Credential *credential, QObject *parent = nullptr)
    ServiceFeatureTable(Esri::ArcGISRuntime::Item *item, qint64 layerId, QObject *parent = nullptr)
    ServiceFeatureTable(Esri::ArcGISRuntime::Item *item, QObject *parent = nullptr)
    virtual ~ServiceFeatureTable() override
    QFuture<QList<Esri::ArcGISRuntime::FeatureEditResult *>> applyEditsAsync(QObject *parent = nullptr)
    double bufferFactor() const
    void clearCache(bool keepLocalEdits = true)
    QString definitionExpression() const
    Esri::ArcGISRuntime::FeatureRequestMode featureRequestMode() const
    QString geodatabaseVersion() const
    Esri::ArcGISRuntime::Item *item() const
    QFuture<void> loadOrRefreshFeaturesAsync(const QList<Esri::ArcGISRuntime::Feature *> &features)
    QFuture<Esri::ArcGISRuntime::FeatureQueryResult *> populateFromServiceAsync(const Esri::ArcGISRuntime::QueryParameters &parameters, bool clearCache, const QStringList &outFields, QObject *parent = nullptr)
    QFuture<Esri::ArcGISRuntime::FeatureQueryResult *> queryFeaturesAsync(const Esri::ArcGISRuntime::QueryParameters &parameters, Esri::ArcGISRuntime::QueryFeatureFields queryFeatureFields, QObject *parent = nullptr)
    QFuture<QList<Esri::ArcGISRuntime::RelatedFeatureQueryResult *>> queryRelatedFeaturesAsync(Esri::ArcGISRuntime::ArcGISFeature *feature, const Esri::ArcGISRuntime::RelatedQueryParameters &parameters, Esri::ArcGISRuntime::QueryFeatureFields queryFeatureFields, QObject *parent = nullptr)
    Esri::ArcGISRuntime::ServiceGeodatabase *serviceGeodatabase() const
    void setBufferFactor(double buffer)
    void setCredential(Esri::ArcGISRuntime::Credential *credential)
    void setDefinitionExpression(const QString &expression)
    void setFeatureRequestMode(Esri::ArcGISRuntime::FeatureRequestMode mode)
    void setGeodatabaseVersion(const QString &version)
    QFuture<void> undoLocalEditsAsync()

    Reimplemented Public Functions

    virtual QString apiKey() const override
    virtual Esri::ArcGISRuntime::Credential *credential() const override
    virtual Esri::ArcGISRuntime::RequestConfiguration requestConfiguration() const override
    virtual void setApiKey(const QString &apiKey) override
    virtual void setRequestConfiguration(const Esri::ArcGISRuntime::RequestConfiguration &requestConfiguration) override
    virtual QUrl url() const override

    Detailed Description

    An instance of this class represents the dataset of an individual layer or table in an ArcGIS map or feature service. The map or feature service may be hosted in the cloud on ArcGIS Online, or on-premises on an ArcGIS Server. To access these services you may need to provide authentication in your application.

    You can construct a ServiceFeatureTable directly from the feature service using its URL or PortalItem. Alternatively, you can obtain a ServiceFeatureTable from a FeatureLayer or a FeatureTable that is part of a Map or Scene. You can also obtain a ServiceFeatureTable directly from its service geodatabase using ServiceGeodatabase::table(qint64).

    The ServiceFeatureTable adopts the loadable pattern so many of its properties are initialized asynchronously after connecting to the service. For more information, see Loadable.

    Display

    If the hasGeometry is true, you can display the features in a Map or Scene. To do this create a FeatureLayer from the feature table and add it to the map or scene's collection of operational layers (GeoModel::operationalLayers). Spatial features are requested in the SpatialReference that matches the Map or Scene and are displayed using the Symbol information defined by the map or feature service.

    Query

    You can query the data in the ServiceFeatureTable based on SQL expressions and/or spatial relationships. Use the QueryParameters object to define your spatial or attribute query and pass it to the queryFeatures() method. If the service feature table is related to any other tables that are part of the map or scene, use the queryRelatedFeatures() method to query the related tables. For more information, see RelatedQueryParameters.

    Edit

    A ServiceFeatureTable can have editable attribute fields, feature templates(FeatureTemplate), feature types (FeatureType), and editing capabilities defined in ArcGISFeatureLayerInfo::capabilities. You can create, delete, and update data in the local cache depending upon whether the service allows those operations, who owns the data, and what ownership-based access control policies are in place. Permission to edit the data is managed by the author of the feature service. Explore isEditable, canAdd, canUpdate(), and canDelete() for information on what is permitted. If the service supports attachments (hasAttachments), you can also view and potentially edit the attachments. If you want to apply your edits to the feature service, you must call the ServiceGeodatabase::applyEdits method on the serviceGeodatabase. This will ensure that the table and any tables involved in geodatabase behavior are updated. Areas that have geodatabase behavior include:

    • Composite relationships
    • Annotation feature layers
    • Utility network association deletion semantics
    • Attribute rules

    Other things to consider:

    If the table's mode is FeatureRequestMode::ManualCache, you must call populateFromServiceAsync(QueryParameters, bool, QStringList), which populates the local table with the features specified by QueryParameters and containing the attributes specified by QStringList. Features are cached for the duration of the session and queries are executed against the cache.

    Contingent Values

    The ServiceFeatureTable supports querying and editing contingent values. See contingentValues() for more information.

    Offline

    You can use a service feature table to access non-spatial tables from feature services where FeatureTable::hasGeometry is false. The feature request mode of the table must be FeatureRequestMode::ManualCache, and you must call populateFromService(QueryParameters, bool, QStringList).

    If you wish to adopt an offline workflow, you can take areas of a ServiceFeatureTable offline using the GeodatabaseSyncTask. If you wish to take a Map offline use the OfflineMapTask. See Build offline applications for more information.

    Feature Request Mode

    The FeatureRequestMode determines whether ServiceFeatureTable features are cached locally (for quicker access by map and scene layers) and whether queries are performed on the local cache or on the server. Consider which of these 3 modes is appropriate for your application:

    • FeatureRequestMode::OnInteractionCache - User interactions (pan or zoom) with the MapView or SceneView request features from the server and cache them locally for the duration of the session. Subsequent interactions with the MapView or SceneView will refresh this local cache. Queries are executed on the local cache or (if requested features are not resident in the cache) on the server. If the network connection is lost then the application can still operate with the local cache. This is the default mode.
    • FeatureRequestMode::OnInteractionNoCache - Your application will display or query features directly from the server. They are not cached locally. This mode ensures that you are working against the latest data, but it has a high network bandwidth since it goes to the server for all interactions (pans, zooms, selects, or queries).
    • FeatureRequestMode::ManualCache - Your application must explicitly call populateFromService() to query the feature service and cache the resulting features in the ServiceFeatureTable. All queries are made against this local cache. You must adopt this mode for tables that contain non-spatial records (see hasGeometry).

    Member Function Documentation

    [explicit] ServiceFeatureTable::ServiceFeatureTable(const QUrl &url, QObject *parent = nullptr)

    Creates a new service feature table object from a given URL.

    • url - The URL of an individual layer or table in an ArcGIS map or feature service.
    • parent - The optional parent QObject.

    [since Esri::ArcGISRuntime 100.1] ServiceFeatureTable::ServiceFeatureTable(Esri::ArcGISRuntime::ServiceFeatureTable *table, const Esri::ArcGISRuntime::RelationshipInfo &relationshipInfo, QObject *parent = nullptr)

    Creates a new service feature table object from the specified table and relationship information.

    • table - The table from which to create a new table.
    • relationshipInfo - The relationship information specifying which table to create.
    • parent - The optional parent QObject.

    This function was introduced in Esri::ArcGISRuntime 100.1.

    ServiceFeatureTable::ServiceFeatureTable(const QUrl &url, Esri::ArcGISRuntime::Credential *credential, QObject *parent = nullptr)

    Constructs a service feature table from a specified url, credential and an optional parent.

    ServiceFeatureTable::ServiceFeatureTable(Esri::ArcGISRuntime::Item *item, qint64 layerId, QObject *parent = nullptr)

    Creates a new service feature table object from a feature service portal item.

    • item - An ArcGIS feature service PortalItem.
    • layerId - The layer id of an individual layer in the ArcGIS feature service represented by the Item.
    • parent - The optional parent QObject.

    See also item.

    [explicit, since Esri::ArcGISRuntime 100.14] ServiceFeatureTable::ServiceFeatureTable(Esri::ArcGISRuntime::Item *item, QObject *parent = nullptr)

    Creates a new service feature table object from a feature service or feature layer portal item.

    • item - A feature service or feature layer PortalItem.
    • parent - The optional parent QObject.

    If the portal item is a feature service, then the ServiceFeatureTable is created from the first layer on the service. If the portal item is a feature layer, then the ServiceFeatureTable is created from the feature layer.

    This function was introduced in Esri::ArcGISRuntime 100.14.

    See also item.

    [override virtual] ServiceFeatureTable::~ServiceFeatureTable()

    Destructor.

    [override virtual, since Esri::ArcGISRuntime 100.10] QString ServiceFeatureTable::apiKey() const

    Reimplements: ApiKeyResource::apiKey() const.

    Returns the API key to access API key enabled services and resources in ArcGIS Online.

    An API key is a unique key used to authorize access to specific services and resources in ArcGIS Online. It is also used to monitor access to those services. An API key is created and managed in the ArcGIS developer dashboard and is tied to a specific ArcGIS account.

    In addition to setting an ArcGISRuntimeEnvironment::apiKey at a global level for your application, you can set it on any class that implements ApiKeyResource. This overrides the ArcGISRuntimeEnvironment::apiKey and enables more granular usage telemetry and management of ArcGIS location resources used by your app.

    Classes that expose an API key property by implementing ApiKeyResource include:

    See ApiKeyResource.

    This function was introduced in Esri::ArcGISRuntime 100.10.

    See also setApiKey().

    [since Esri::ArcGISRuntime 200.2] QFuture<QList<Esri::ArcGISRuntime::FeatureEditResult *>> ServiceFeatureTable::applyEditsAsync(QObject *parent = nullptr)

    Uploads any changes to the local table to the feature service.

    • parent - An optional parent.

    applyEditsAsync is meant to be used for single table workflows or tables without geodatabase behavior (see below). If an edit on this table can cause an edit to another table due to geodatabase behavior, it is highly recommended to use ServiceGeodatabase::applyEditsAsync instead to prevent data inconsistency, so that dependent edits are all applied or none are (if an error occurs).

    For example, when tables have a composite relationship, applying the delete of a destination feature in a composite relationship deletion will only delete the destination feature on the server, therefore causing inconsistency in the data.

    Areas which have geodatabase behavior:

    • Composite relationships
    • Annotation feature layers
    • Utility network association deletion semantics
    • Attribute rules

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    See also FeatureServiceSessionType.

    double ServiceFeatureTable::bufferFactor() const

    Returns the factor used to calculate a buffered extent around the current visible area when requesting features from a service.

    New features are requested from the service if the visible area of the MapView exceeds the buffered extent. A change in the visible area can result from any user interaction with the MapView, such as a pan or zoom action. The buffer factor is applied when the FeatureRequestMode is in either FeatureRequestMode::OnInteractionCache or FeatureRequestMode::OnInteractionNoCache.

    The default value is 2 (twice the current extent). The maximum value is 10. If it is set to 0 or 1, the buffered extent will equal the visible map area.

    See also setBufferFactor().

    void ServiceFeatureTable::clearCache(bool keepLocalEdits = true)

    Clears all the data in the table, including any temporary edits.

    keepLocalEdits If true, then edited rows in the table won't be cleared.

    [override virtual] Esri::ArcGISRuntime::Credential *ServiceFeatureTable::credential() const

    Reimplements: RemoteResource::credential() const.

    Returns the security credential used to access the feature service.

    Only applicable if the service is secured.

    See also setCredential().

    [since Esri::ArcGISRuntime 100.2] QString ServiceFeatureTable::definitionExpression() const

    Returns an expression (SQL where clause) to filter features queried in this table.

    The definition expression string uses the SQL-92 where clause syntax (https://en.wikipedia.org/wiki/SQL-92). Be sure to escape special characters in the expression string as required for your platform. The DATE keyword expects the date format yyyy-mm-dd and the TIMESTAMP keyword expects the time stamp format yyyy-mm-dd hh:mm:ss. For more information, see the ArcGIS Blog article "Querying Feature Services Date-Time Queries".

    This function was introduced in Esri::ArcGISRuntime 100.2.

    See also setDefinitionExpression().

    Esri::ArcGISRuntime::FeatureRequestMode ServiceFeatureTable::featureRequestMode() const

    Defines when features and non-spatial records are requested from the feature service.

    The default value is FeatureRequestMode::OnInteractionCache.

    You cannot change the feature request mode after the table is successfully loaded.

    See also setFeatureRequestMode().

    QString ServiceFeatureTable::geodatabaseVersion() const

    Returns the service geodatabase version name.

    This property is populated if the ServiceFeatureTable is provided by a layer or a table in a web map or if the ServiceFeatureTable is created using ServiceGeodatabase::table(qint64).

    The default geodatabase version has the string value "sde.DEFAULT".

    See also setGeodatabaseVersion().

    [since Esri::ArcGISRuntime 100.14] Esri::ArcGISRuntime::Item *ServiceFeatureTable::item() const

    Returns the Item that defines the service feature table.

    {ServiceFeatureTable(Item, qint64)}

    This function was introduced in Esri::ArcGISRuntime 100.14.

    See also Esri::ArcGISRuntime::ServiceFeatureTable::ServiceFeatureTable.

    [since Esri::ArcGISRuntime 200.2] QFuture<void> ServiceFeatureTable::loadOrRefreshFeaturesAsync(const QList<Esri::ArcGISRuntime::Feature *> &features)

    Loads all attributes and geometries for features that have not been loaded and fetches attributes and geometries for previously loaded features.

    • features - The features to be loaded or refreshed.

    Features returned from ServiceFeatureTable::queryFeaturesAsync or ServiceFeatureTable::queryRelatedFeaturesAsync may be in the minimally loaded state (minimum attributes required for rendering and no m-values). To load all attributes, pass a mutable array of the features to this method.

    Any feature requested, but not returned, by the server will have its object id cleared (set to an invalid negative value) to indicate it is no longer associated with the service feature table.

    After calling this method, any non-applied edits on the table will be lost.

    This method will not refresh feature attachments. Use AttachmentListModel::fetchAttachmentsAsync to retrieve attachments.

    All features loaded or refreshed by this method will have m-values if defined by the service. Note that an m-value may be NaN. This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    [since Esri::ArcGISRuntime 200.2] QFuture<Esri::ArcGISRuntime::FeatureQueryResult *> ServiceFeatureTable::populateFromServiceAsync(const Esri::ArcGISRuntime::QueryParameters &parameters, bool clearCache, const QStringList &outFields, QObject *parent = nullptr)

    Queries the feature service and places the resulting features in the local table, which is cached for the duration of the session. The ServiceFeatureTable must have its featureRequestMode set to FeatureRequestMode::ManualCache.

    • parameters - Options for controlling the operation.
    • clearCache - true, if you want to clear the local cache before populating the local table. false, if you want to append the features to the local table.
    • outFields - A QStringList. Each string is the name of a field to be used when populating the cache. If the array contains the single element "*", then all fields will be used. If the ObjectID field string name is not provided as part of the QStringList, no features will be returned for this method.
    • parent - An optional parent.

    This method is useful for non-geographic data. It's also helpful when you want to avoid accessing the service for a feature whose geometry is in the current extent of the map or scene.

    Specifying an empty QStringList for outfields results in the minimum set of fields being used to populate the local table. This is the same set of fields described for FeatureRequestMode::OnInteractionCache or FeatureRequestMode::OnInteractionNoCache. This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    See also FeatureServiceSessionType.

    [since Esri::ArcGISRuntime 200.2] QFuture<Esri::ArcGISRuntime::FeatureQueryResult *> ServiceFeatureTable::queryFeaturesAsync(const Esri::ArcGISRuntime::QueryParameters &parameters, Esri::ArcGISRuntime::QueryFeatureFields queryFeatureFields, QObject *parent = nullptr)

    Queries features from this table's cache and/or from the feature service used to create this table.

    • parameters - Options for controlling the operation.
    • queryFeatureFields - Options for controlling what fields are in the features of the query result.
    • parent - An optional parent.

    If the request mode of the table is FeatureRequestMode::ManualCache, then the query is always performed on the local table.

    If the mode is FeatureRequestMode::OnInteractionCache, then the query is performed on the local cache, provided that the geometries of the features are within an extent that has been cached; otherwise, the query is performed on the server.

    If the mode is FeatureRequestMode::OnInteractionNoCache, the query is always performed on the server.

    QueryFeatureFields controls which fields will be included with the returned features. The options are:

    • If the service feature table FeatureRequestMode is onInteractionCache or onInteractionNoCache, the table will initially contains features with a minimum set of attribute required for rendering. To access all the feature's attributes you must load the features QueryFeatureFields::LoadAll automatically loads the returned features into the local table and makes all attributes available.

    Note that you can query any attribute defined by the feature service's table. If the attribute is not in the set of attributes in your local table, the query will be performed on the server. This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    See also FeatureServiceSessionType.

    [since Esri::ArcGISRuntime 200.2] QFuture<QList<Esri::ArcGISRuntime::RelatedFeatureQueryResult *>> ServiceFeatureTable::queryRelatedFeaturesAsync(Esri::ArcGISRuntime::ArcGISFeature *feature, const Esri::ArcGISRuntime::RelatedQueryParameters &parameters, Esri::ArcGISRuntime::QueryFeatureFields queryFeatureFields, QObject *parent = nullptr)

    Queries for related features in this service feature table using the provided parameters and query feature fields. See ServiceFeatureTable::queryFeaturesAsync for more details.

    • feature - The feature for which to query related features.
    • parameters - The related query parameters.
    • queryFeatureFields - Enumeration indicating which fields to return from the query.
    • parent - An optional parent.

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    See also FeatureServiceSessionType.

    [override virtual, since Esri::ArcGISRuntime 100.1] Esri::ArcGISRuntime::RequestConfiguration ServiceFeatureTable::requestConfiguration() const

    Reimplements: RemoteResource::requestConfiguration() const.

    Returns the RequestConfiguration in use by this ServiceFeatureTable.

    This function was introduced in Esri::ArcGISRuntime 100.1.

    See also setRequestConfiguration().

    [since Esri::ArcGISRuntime 100.9] Esri::ArcGISRuntime::ServiceGeodatabase *ServiceFeatureTable::serviceGeodatabase() const

    Returns the service geodatabase this service feature table is part of.

    This property is populated if the ServiceFeatureTable is provided by a layer or a table in a web map or if the ServiceFeatureTable is created using ServiceGeodatabase::table(qint64).

    This function was introduced in Esri::ArcGISRuntime 100.9.

    [override virtual, since Esri::ArcGISRuntime 100.10] void ServiceFeatureTable::setApiKey(const QString &apiKey)

    Reimplements: ApiKeyResource::setApiKey(const QString &apiKey).

    Sets the apiKey to apiKey.

    This function was introduced in Esri::ArcGISRuntime 100.10.

    See also apiKey.

    void ServiceFeatureTable::setBufferFactor(double buffer)

    Sets the bufferFactor to buffer.

    See also bufferFactor.

    [since Esri::ArcGISRuntime 100.14] void ServiceFeatureTable::setCredential(Esri::ArcGISRuntime::Credential *credential)

    Sets the credential to credential.

    This function was introduced in Esri::ArcGISRuntime 100.14.

    See also credential.

    [since Esri::ArcGISRuntime 100.2] void ServiceFeatureTable::setDefinitionExpression(const QString &expression)

    Sets the definitionExpression to an expression.

    This function was introduced in Esri::ArcGISRuntime 100.2.

    See also definitionExpression.

    void ServiceFeatureTable::setFeatureRequestMode(Esri::ArcGISRuntime::FeatureRequestMode mode)

    Sets the featureRequestMode to mode.

    See also featureRequestMode.

    void ServiceFeatureTable::setGeodatabaseVersion(const QString &version)

    Sets the geodatabaseVersion to version.

    See also geodatabaseVersion.

    [override virtual, since Esri::ArcGISRuntime 100.1] void ServiceFeatureTable::setRequestConfiguration(const Esri::ArcGISRuntime::RequestConfiguration &requestConfiguration)

    Reimplements: RemoteResource::setRequestConfiguration(const Esri::ArcGISRuntime::RequestConfiguration &requestConfiguration).

    Sets configuration parameters used for network requests sent by this ServiceFeatureTable to requestConfiguration.

    This function was introduced in Esri::ArcGISRuntime 100.1.

    See also requestConfiguration().

    [since Esri::ArcGISRuntime 200.2] QFuture<void> ServiceFeatureTable::undoLocalEditsAsync()

    Undoes all of the local edits since the last server acknowledgment. undoLocalEdits is meant to be used for single table workflows or tables without geodatabase behavior (see below). If the service which the table belongs to has geodatabase behavior (see below), it is highly recommended to use ServiceGeodatabase::undoLocalEdits. Undoing edits in one table can cause data inconsistencies between the local cache and the service if undoLocalEdits is used.

    For example, when tables have a composite relationship, undoing only the origin feature would violate the composite relationship rule that an origin and destination feature must be either deleted together or not at all.

    Areas which have geodatabase behavior:

    • Composite relationships
    • Annotation feature layers
    • Utility network association deletion semantics
    • Attribute rules

    This method returns a QFuture for the asynchronous operation. Use future.then() to continue processing when the operation completes. Use future.onFailed() to handle exceptions of type ErrorException.

    See Working with QFuture for further details.

    This function was introduced in Esri::ArcGISRuntime 200.2.

    See also FeatureServiceSessionType.

    [override virtual] QUrl ServiceFeatureTable::url() const

    Reimplements: RemoteResource::url() const.

    Returns the URL of the service feature table.

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