JavaScript ArcGIS TopFeaturesQuery用法及代碼示例

AMD: require(["esri/rest/support/TopFeaturesQuery"], (TopFeaturesQuery) => { /* code goes here */ });

ESM: import TopFeaturesQuery from "@arcgis/core/rest/support/TopFeaturesQuery";

類： esri/rest/support/TopFeaturesQuery

繼承: TopFeaturesQuery > Accessor

自從：用於 JavaScript 4.20 的 ArcGIS API

此類定義用於從 FeatureLayer 執行 top features queries 的參數。一旦定義了 TopFeaturesQuery 對象的屬性，就可以將其傳遞到服務器端 FeatureLayer 上的可執行函數中，該函數可以返回包含組內特征的 FeatureSet。例如，您可以使用 FeatureLayer 的queryTopFeatures() 方法來查詢美國每個州人口最多的三個縣。

此類具有許多與Query 類相同的屬性。但是，與 Query 類不同，此類不支持 outStatistics 及其相關參數或 returnDistinctValues 等屬性。

// query the top three most populous counties from each state.
// Results will be ordered based the population of each county in descending order
// top query will run against all features available in the service
const query = new TopFeaturesQuery({
  outFields: ["State, Pop_total, County"],
  topFilter: new TopFilter({
    topCount: 3,
    groupByFields: ["State"],
    orderByFields: ["Pop_total DESC"]
  })
});
featureLayer.queryTopFeatures(query)
  .then(function(response){
     // returns a feature set with features containing the most populous
     // three counties in each state ordered by population.
     // The following attributes are returned as well: State, Pop_total, County
   });

熱門特征查詢分為三種類型：屬性查詢、空間查詢和時間查詢。您可以查詢這些類別之一中的要素，或者在單個查詢中使用每個類別的元素。運行熱門函數查詢時，必須始終設置 topFilter 參數。

屬性查詢

要根據屬性值查詢熱門要素，請在 where 屬性中與 topFilter 屬性一起指定 SQL where 子句。設置查詢的outFields將限製查詢返回的屬性。如果您的應用不需要每個函數的所有屬性，這可以提高查詢速度。

例如，如果人口超過1,000,000，您可以使用where和topFilter參數查詢每個國家人口最多的前三個城市。

const query = new TopFeaturesQuery({
  where: "Population >= 1000000",
  outFields: ["Country, Population, Name"],
  topFilter: new TopFilter({
    topCount: 3,
    groupByFields: ["Country"],
    orderByFields: [`Population DESC`]
  })
});
featureLayer.queryTopFeatures(query)
  .then(function(response){
     // returns a feature set with features containing the most populous three cities
     // in each country. The query will run only against cities where the population is
     // over one million.
   });

空間查詢

您可以按幾何/位置查詢熱門要素。雖然此工作流程中不需要 where，但您可以使用 where 作為查詢的一部分以獲得更精確的結果。除了幾何屬性之外，還必須設置 topFilter 屬性。要執行空間查詢，您必須將幾何參數設置為Geometry 對象並指定有效的空間關係。您可以選擇提供查詢距離和單位，以針對給定幾何圖形周圍的緩衝區查詢要素。

例如，要在鼠標移動 10 英裏範圍內查詢每個分區類別中的兩座最高建築物，您可以執行以下操作：

view.on("pointer-move", function(event){
  const query = new TopFeaturesQuery({
    outFields: ["Zoning, Floors, Year"],
    topFilter: new TopFilter({
      topCount: 2,
      groupByFields: ["Zoning"],
      orderByFields: ["Floors DESC"]
    }),
    geometry: view.toMap(event),
    spatialRelationship:  "intersects",
    units: "miles",
    distance: 10,
    returnGeometry: true
  });
  featureLayer.queryTopFeatures(query)
    .then(function(response){
       // returns two tallest buildings in zoning category within a given geometry
       // The following attributes are returned as well: Zoning, Floors, Year
     });
});

例如，您還可以使用 where 來返回 10 英裏緩衝區內特定住宅分區中最高的建築物。

時間查詢

您可以通過指定 timeExtent 屬性來查詢基於給定時間範圍的熱門要素。僅當要素服務發布時包含 timeInfo 信息時，時態查詢才會返回結果。時間查詢還可以與屬性和幾何查詢相結合。

例如，您可以使用 timeExtent 和 topFilter 參數來查詢具有最高風速的颶風軌跡，並按給定時間範圍內的颶風類別進行分組。

// query hurricanes that took place in 1992 and
// return a hurricane track with the highest wind speed in each category
const query = new TopFeaturesQuery({
  outFields: ["STAGE, WINDSPEED, PRESSURE"],
  topFilter: new TopFilter({
    topCount: 1,
    groupByFields: ["STAGE"],
    orderByFields: ["WINDSPEED DESC"]
  }),
  timeExtent: {
    start: new Date(1992, 0, 1),
    end: new Date(1992, 11, 31)
  }
});
featureLayer.queryTopFeatures(query)
  .then(function(response){
     // returns a hurricane with the highest wind speed
     // in each stage... the query will only run against
    // hurricanes  that happened in 1992
   });