@arcgis/core/rest/query.d.ts

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

/**
 * Executes different types of query operations on a layer. The most common
 * method used is [executeQueryJSON()](https://developers.arcgis.com/javascript/latest/references/core/rest/query/#executeQueryJSON), which executes the query for JSON results as defined in the
 * [Query](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/) object that is passed as a parameter to the function.
 * `executeQueryJSON()` returns a Promise that resolves to a
 * [FeatureSet](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FeatureSet/), which contains the features in the layer
 * that satisfy the [Query](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/).
 *
 * You can also obtain the [number of features](https://developers.arcgis.com/javascript/latest/references/core/rest/query/#executeForCount) that satisfy the
 * query, the [extent](https://developers.arcgis.com/javascript/latest/references/core/rest/query/#executeForExtent) of features, [related features or records](https://developers.arcgis.com/javascript/latest/references/core/rest/query/#executeRelationshipQuery)
 * associated with a feature, [attachments](https://developers.arcgis.com/javascript/latest/references/core/rest/query/#executeAttachmentQuery) for features or the [featureIds](https://developers.arcgis.com/javascript/latest/references/core/rest/query/#executeForIds)
 * of features.
 *
 * For example, when working with a feature layer of world cities, to obtain a
 * [FeatureSet](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FeatureSet/) of cities with a population greater than
 * one million people, use the code below.
 *
 * @since 4.19
 * @see [Query](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/)
 * @see [AttachmentQuery](https://developers.arcgis.com/javascript/latest/references/core/rest/support/AttachmentQuery/)
 * @see [RelationshipQuery](https://developers.arcgis.com/javascript/latest/references/core/rest/support/RelationshipQuery/)
 * @see [FeatureSet](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FeatureSet/)
 * @example
 * // query featureLayer for cities with a population greater than one million people
 * const query = await $arcgis.import("@arcgis/core/rest/query");
 *
 * // url to the layer of interest to query
 * const url = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/SampleWorldCities/MapServer/0";
 *
 * const { features } = await query.executeQueryJSON(url, {
 *   where: "POP > 1000000"
 * });
 */
import type Extent from "../geometry/Extent.js";
import type SpatialReference from "../geometry/SpatialReference.js";
import type AttachmentInfo from "./query/support/AttachmentInfo.js";
import type AttachmentQuery from "./support/AttachmentQuery.js";
import type FeatureSet from "./support/FeatureSet.js";
import type Query from "./support/Query.js";
import type RelationshipQuery from "./support/RelationshipQuery.js";
import type TopFeaturesQuery from "./support/TopFeaturesQuery.js";
import type { RequestOptions } from "../request/types.js";
import type { LayerMetadata } from "./types.js";
import type { QueryProperties } from "./support/Query.js";
import type { ObjectId } from "../views/types.js";

/**
 * Query information about attachments associated with features from a
 * [feature layer](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/) specified in the url parameter. It will return an error if
 * the layer's [capabilities.data.supportsAttachment](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/#capabilities) is set to false.
 *
 * @param url - URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
 * @param attachmentQuery - Specifies the attachment parameters for query.
 * @param requestOptions - Additional [options](https://developers.arcgis.com/javascript/latest/references/core/request/#request) to be used for the data request.
 * @returns When resolved, returns an object containing
 * [AttachmentInfos](https://developers.arcgis.com/javascript/latest/references/core/rest/query/support/AttachmentInfo/) grouped by the source
 * feature objectIds.
 * @see [capabilities.data.supportsAttachment](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/#capabilities)
 * @see [capabilities.operations.supportsQueryAttachments](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/#capabilities)
 */
export function executeAttachmentQuery(url: string, attachmentQuery: AttachmentQuery, requestOptions?: RequestOptions): Promise<Record<string, AttachmentInfo[]>>;

/**
 * Gets a count of the number of features that satisfy the input query.
 *
 * @param url - URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
 * @param query - Specifies the attributes and spatial filter of the query.
 * @param requestOptions - Additional [options](https://developers.arcgis.com/javascript/latest/references/core/request/#request) to be used for the data request.
 * @returns When resolved, the result is the number of features that satisfy the input query.
 * @example
 * const query = await $arcgis.import("@arcgis/core/rest/query");
 *
 * // url to the layer of interest to query
 * const url = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3";
 *
 * const count = await query.executeForCount(url, {
 *   where: "POP07_SQMI > 100"
 * });
 */
export function executeForCount(url: string, query: Query | QueryProperties, requestOptions?: RequestOptions): Promise<number>;

/**
 * Gets the extent of the features that satisfy the input query. The count of features that
 * satisfy the input query is returned upon resolution as well.
 *
 * @param url - URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
 * @param query - Specifies the attributes and spatial filter of the query.
 * @param requestOptions - Additional [options](https://developers.arcgis.com/javascript/latest/references/core/request/#request) to be used for the data request.
 * @returns When resolved, returns the extent and count of the features
 * that satisfy the input query. See the object specification table below for details.
 * Property | Type | Description
 * ---------|------|-------------
 * count | number | The number of features that satisfy the input query.
 * extent | [Extent](https://developers.arcgis.com/javascript/latest/references/core/geometry/Extent/) \| null | The extent of the features that satisfy the query.
 */
export function executeForExtent(url: string, query: Query | QueryProperties, requestOptions?: RequestOptions): Promise<{
    count: number;
    extent: Extent | null;
}>;

/**
 * Executes a [Query](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/) against the layer specified in the url parameter.
 * The result is an array of the object IDs of features that satisfy the input query.
 * There is no limit to the number of object IDs returned in the ID array response.
 *
 * @param url - URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
 * @param query - Specifies the attributes and spatial filter of the query.
 * @param requestOptions - Additional [options](https://developers.arcgis.com/javascript/latest/references/core/request/#request) to be used for the data request.
 * @param layerMetadata - Additional query options.
 * @returns When resolved, the result is an array of object IDs for
 * features that satisfy the input query.
 * @example
 * const query = await $arcgis.import("@arcgis/core/rest/query");
 *
 * // url to the layer of interest to query
 * const url = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3";
 *
 * const ids = await query.executeForIds(url, {
 *   where: "SUB_REGION = 'Pacific'"
 * });
 * console.log(ids);  // an array of object IDs
 */
export function executeForIds(url: string, query: Query | QueryProperties, requestOptions?: RequestOptions, layerMetadata?: LayerMetadata): Promise<ObjectId[]>;

/**
 * Executes a [TopFeaturesQuery](https://developers.arcgis.com/javascript/latest/references/core/rest/support/TopFeaturesQuery/) against a feature service and returns
 * the count of features or records that satisfy the query.
 *
 * > [!WARNING]
 * >
 * > **Known Limitations**
 * >
 * > Currently, the `executeForTopCount` is only supported with server-side [FeatureLayers](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/).
 *
 * @param url - URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
 * @param topFeaturesQuery - Specifies the attributes, spatial, temporal, and top
 * filter of the query. The [TopFeaturesQuery.topFilter](https://developers.arcgis.com/javascript/latest/references/core/rest/support/TopFeaturesQuery/#topFilter) parameter must be set.
 * @param requestOptions - Additional [options](https://developers.arcgis.com/javascript/latest/references/core/request/#request) to be used for the data request.
 * @returns When resolved, returns the number of features satisfying the query.
 * @since 4.25
 * @see [Query and filter guide](https://developers.arcgis.com/javascript/latest/query-filter/)
 * @see [TopFeaturesQuery](https://developers.arcgis.com/javascript/latest/references/core/rest/support/TopFeaturesQuery/)
 * @see [TopFilter](https://developers.arcgis.com/javascript/latest/references/core/rest/support/TopFilter/)
 * @example
 * // set the query to return a count
 * // of features that has most sales grouped by regions.
 * // top query will run against all features available in the service
 * const query = await $arcgis.import("@arcgis/core/rest/query");
 *
 * const count = await query.executeForTopCount(url, { // autocast to TopFeaturesQuery
 *   where: "mag >= 6",
 *   topFilter: { // autocast to TopFilter
 *     topCount: 1,
 *     groupByFields: ["Region"],
 *     orderByFields: ["Sales DESC"],
 *   },
 * });
 */
export function executeForTopCount(url: string, topFeaturesQuery: TopFeaturesQuery, requestOptions?: RequestOptions): Promise<number>;

/**
 * Executes a [TopFeaturesQuery](https://developers.arcgis.com/javascript/latest/references/core/rest/support/TopFeaturesQuery/) against a feature service and returns
 * the [Extent](https://developers.arcgis.com/javascript/latest/references/core/geometry/Extent/) of features that satisfy the query.
 *
 * > [!WARNING]
 * >
 * > **Known Limitations**
 * >
 * > Currently, the `executeForTopExtents` is only supported with server-side [FeatureLayers](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/).
 *
 * @param url - URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
 * @param topFeaturesQuery - Specifies the attributes, spatial, temporal, and top
 * filter of the query. The [TopFeaturesQuery.topFilter](https://developers.arcgis.com/javascript/latest/references/core/rest/support/TopFeaturesQuery/#topFilter) parameter must be set.
 * @param requestOptions - Additional [options](https://developers.arcgis.com/javascript/latest/references/core/request/#request) to be used for the data request.
 * @returns When resolved, returns the extent and count of the features
 * that satisfy the input query. See the object specification table below for details.
 * Property | Type | Description
 * ---------|------|-------------
 * count | Number | The number of features that satisfy the query.
 * extent | [Extent](https://developers.arcgis.com/javascript/latest/references/core/geometry/Extent/) \| null | The extent of features that satisfy the query.
 * @since 4.25
 * @see [Query and filter guide](https://developers.arcgis.com/javascript/latest/query-filter/)
 * @see [TopFeaturesQuery](https://developers.arcgis.com/javascript/latest/references/core/rest/support/TopFeaturesQuery/)
 * @see [TopFilter](https://developers.arcgis.com/javascript/latest/references/core/rest/support/TopFilter/)
 * @example
 * // Get the count and extent of the three highest magnitude earthquakes in each region.
 *
 * const query = await $arcgis.import("@arcgis/core/rest/query");
 *
 * const { count, extent } = await query.executeForTopExtents(url, { // autocast to TopFeaturesQuery
 *   where: "mag >= 6",
 *   topFilter: { // autocast to TopFilter
 *     topCount: 3,
 *     groupByFields: ["region"],
 *     orderByFields: ["mag DESC"]
 *   }
 * });
 */
export function executeForTopExtents(url: string, topFeaturesQuery: TopFeaturesQuery, requestOptions?: RequestOptions): Promise<{
    count: number;
    extent: Extent | null;
}>;

/**
 * Executes a [TopFeaturesQuery](https://developers.arcgis.com/javascript/latest/references/core/rest/support/TopFeaturesQuery/) against a feature service and returns an
 * array of Object IDs of features that satisfy the query.
 *
 * > [!WARNING]
 * >
 * > **Known Limitations**
 * >
 * > Currently, the `executeForTopIds` is only supported with server-side [FeatureLayers](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/).
 *
 * @param url - URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
 * @param topFeaturesQuery - Specifies the attributes, spatial, temporal, and top
 * filter of the query. The [TopFeaturesQuery.topFilter](https://developers.arcgis.com/javascript/latest/references/core/rest/support/TopFeaturesQuery/#topFilter) parameter must be set.
 * @param requestOptions - Additional [options](https://developers.arcgis.com/javascript/latest/references/core/request/#request) to be used for the data request.
 * @returns When resolved, returns an array of numbers representing the object IDs of features
 * satisfying the query.
 * @since 4.25
 * @see [Query and filter guide](https://developers.arcgis.com/javascript/latest/query-filter/)
 * @see [TopFeaturesQuery](https://developers.arcgis.com/javascript/latest/references/core/rest/support/TopFeaturesQuery/)
 * @see [TopFilter](https://developers.arcgis.com/javascript/latest/references/core/rest/support/TopFilter/)
 * @example
 * // Get the objectIds top three earthquakes
 * // grouped by regions and ordered by their magnitude levels
 * // top query will only run against earthquakes that have mag >=6.
 *
 * const query = await $arcgis.import("@arcgis/core/rest/query");
 *
 * const ids = await query.executeForTopIds(url, { // autocast to TopFeaturesQuery
 *   where: "mag >= 6",
 *   topFilter: { // autocast to TopFilter
 *     topCount: 3,
 *     groupByFields: ["region"],
 *     orderByFields: ["mag DESC"]
 *   }
 * });
 */
export function executeForTopIds(url: string, topFeaturesQuery: TopFeaturesQuery, requestOptions?: RequestOptions): Promise<number[]>;

/**
 * Executes a [Query](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/) against the layer specified in the url parameter. The result is returned as a
 * [FeatureSet](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FeatureSet/) containing an array of [Graphic](https://developers.arcgis.com/javascript/latest/references/core/Graphic/)
 * features, which can be added to the map. This array will not be populated if no results are found.
 *
 * @param url - URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
 * @param query - Specifies the attributes and spatial filter of the query.
 * @param requestOptions - Additional [options](https://developers.arcgis.com/javascript/latest/references/core/request/#request) to be used for the data request.
 * @param layerMetadata - Additional query options.
 * @returns When resolved, a [FeatureSet](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FeatureSet/) containing
 * an array of graphic features is returned.
 * @example
 * const query = await $arcgis.import("@arcgis/core/rest/query");
 *
 * const url = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3";
 * const { features } = await query.executeQueryJSON(url, {
 *   where: "STATE_NAME = 'Washington'",
 *   outSpatialReference: { wkid: 4269 },
 *   returnGeometry: true,
 *   outFields: ["HOUSEHOLDS"],
 * });
 */
export function executeQueryJSON(url: string, query: Query | QueryProperties, requestOptions?: RequestOptions, layerMetadata?: LayerMetadata): Promise<FeatureSet>;

/**
 * Executes a [Query](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/) against the layer specified in the url parameter. The result is returned as a
 * [FeatureSet](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FeatureSet/). A [FeatureSet](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FeatureSet/) contains an array of [Graphic](https://developers.arcgis.com/javascript/latest/references/core/Graphic/)
 * features, which can be added to the map. This array will not be populated if no results are found.
 *
 * @param url - URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
 * @param query - Specifies the attributes and spatial filter of the query.
 * @param requestOptions - Additional [options](https://developers.arcgis.com/javascript/latest/references/core/request/#request) to be used for the data request.
 * @param layerMetadata - Additional query options.
 * @returns When resolved, a [FeatureSet](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FeatureSet/) containing
 * an array of graphics is returned.
 * @example
 * const query = await $arcgis.import("@arcgis/core/rest/query");
 *
 * const url = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3";
 * const { features } = await query.executeQueryPBF(url, {
 *   where: "STATE_NAME = 'Washington'",
 *   outSpatialReference: { wkid: 4269 },
 *   returnGeometry: true,
 *   outFields: ["HOUSEHOLDS"],
 * });
 */
export function executeQueryPBF(url: string, query: Query | QueryProperties, requestOptions?: RequestOptions, layerMetadata?: LayerMetadata): Promise<FeatureSet>;

/**
 * Executes a [RelationshipQuery](https://developers.arcgis.com/javascript/latest/references/core/rest/support/RelationshipQuery/) against the layer or table specified in the url parameter.
 * If the query is successful, the returned results are
 * [FeatureSets](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FeatureSet/) grouped by source layer or table objectIds.
 *
 * @param url - URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
 * @param relationshipQuery - Specifies relationship parameters
 * for querying related features or records from a layer or a table.
 * @param requestOptions - Additional [options](https://developers.arcgis.com/javascript/latest/references/core/request/#request) to be used for the data request.
 * @returns When resolved, the results are [FeatureSets](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FeatureSet/)
 * grouped by source layer or table objectIds. Each [FeatureSet](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FeatureSet/) contains an array of [Graphic](https://developers.arcgis.com/javascript/latest/references/core/Graphic/)
 * features including the values of the fields requested by the user.
 * @example
 * const [query, RelationshipQuery] = await $arcgis.import([
 *   "@arcgis/core/rest/query.js",
 *   "@arcgis/core/rest/support/RelationshipQuery.js",
 * ]);
 *
 * // url to the layer of interest to query
 * const url = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/0";
 *
 * // specify relationship query parameter
 * const queryRelationship = new RelationshipQuery({
 *    outFields: ["*"],
 *    relationshipId: relationshipId,
 *    objectIds: [11, 22]
 * });
 *
 * // query related features that meet the query parameters
 * const featureSet = await query.executeRelationshipQuery(url, queryRelationship);
 * console.log("query results", featureSet);
 */
export function executeRelationshipQuery(url: string, relationshipQuery: RelationshipQuery, requestOptions?: RequestOptions): Promise<Record<string, FeatureSet>>;

/**
 * Executes a [TopFeaturesQuery](https://developers.arcgis.com/javascript/latest/references/core/rest/support/TopFeaturesQuery/) against a feature service and returns a
 * [FeatureSet](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FeatureSet/) once the promise resolves.
 * The [FeatureSet](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FeatureSet/) contains an array of top [features](https://developers.arcgis.com/javascript/latest/references/core/Graphic/)
 * grouped and ordered by specified fields. For example, you can call this method to query top three counties grouped
 * by state names while ordering them based on their populations in a descending order.
 *
 * > [!WARNING]
 * >
 * > **Known Limitations**
 * >
 * > Currently, the `executeTopFeaturesQuery` is only supported with server-side [FeatureLayers](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/).
 *
 * @param url - URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
 * @param topFeaturesQuery - Specifies the attributes, spatial, temporal, and top
 * filter of the query. The [TopFeaturesQuery.topFilter](https://developers.arcgis.com/javascript/latest/references/core/rest/support/TopFeaturesQuery/#topFilter) parameter must be set.
 * @param outSpatialReference - The desired output spatial reference.
 * @param requestOptions - Additional [options](https://developers.arcgis.com/javascript/latest/references/core/request/#request) to be used for the data request.
 * @returns When resolved, returns a [FeatureSet](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FeatureSet/) containing
 * an array of features that are grouped and ordered specified fields.
 * @since 4.25
 * @see [Sample - Aggregate spatial statistics](https://developers.arcgis.com/javascript/latest/sample-code/featurelayer-query-aggregate/)
 * @see [Query and filter guide](https://developers.arcgis.com/javascript/latest/query-filter/)
 * @see [TopFeaturesQuery](https://developers.arcgis.com/javascript/latest/references/core/rest/support/TopFeaturesQuery/)
 * @see [TopFilter](https://developers.arcgis.com/javascript/latest/references/core/rest/support/TopFilter/)
 * @example
 * // Query the most visited national parks in each state
 * // and order them by the most visited
 * // query will run against all features available in the service
 *
 * const query = await $arcgis.import("@arcgis/core/rest/query");
 *
 * const url = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3";
 * const { features } = await query.executeTopFeaturesQuery(url, { // autocast to TopFeaturesQuery
 *   outFields: ["State, TOTAL, Park"],
 *   topFilter: {  // autocast to TopFilter
 *     topCount: 1,
 *     groupByFields: ["State"],
 *     orderByFields: ["TOTAL DESC"]
 *   },
 * });
 */
export function executeTopFeaturesQuery(url: string, topFeaturesQuery: TopFeaturesQuery, outSpatialReference: SpatialReference, requestOptions?: RequestOptions): Promise<FeatureSet>;