7.14. 分析查询¶

GeoMesa通过GeoTools查询提示提供高级查询功能。您可以使用这些提示来控制查询处理的各个方面或触发分布式分析处理。看见设置查询提示有关设置查询提示的详细信息，请参阅。

7.14.1. 特征采样¶

GeoMesa可以使用统计抽样来返回一定百分比的结果，而不是返回查询的所有要素。在渲染地图或存在太多没有意义的要素时，这会很有用。

要素既可以绝对采样，也可以按特定属性采样。例如，在给定轨迹中的一系列点的情况下，您可能希望按轨迹标识符来采样，以便不会完全采样出任何轨迹。

采样值应为(0，1)范围内的浮点数，表示将返回的要素的小数值。由于分布式处理，不能保证返回的实际计数等于请求的百分比--但是，功能永远不会少于请求的百分比。例如，如果您以10%的比例对5个要素进行采样，则根据数据在集群中的分布情况，您将返回1到5个要素。

采样也可以与下面提到的其他分析查询结合使用。

钥匙	类型	地球服务器转换
QueryHints.SAMPLING	浮标	任何浮点数
QueryHints.SAMPLE_BY	字符串-属性名称(可选)	任何字符串

import org.locationtech.geomesa.index.conf.QueryHints;

// returns 10% of features, threaded by 'track' attribute
query.getHints().put(QueryHints.SAMPLING(), new Float(0.1));
query.getHints().put(QueryHints.SAMPLE_BY(), "track");

import org.locationtech.geomesa.index.conf.QueryHints

// returns 10% of features, threaded by 'track' attribute
query.getHints.put(QueryHints.SAMPLING, 0.1f)
query.getHints().put(QueryHints.SAMPLE_BY, "track");

...&viewparams=SAMPLING:0.1

7.14.2. 密度查询¶

要填充热点图或其他预先渲染的地图，GeoMesa可以使用服务器端聚合将要素映射到像素。这会导致网络流量大大减少，从而使查询速度大大加快。

密度查询的结果是编码的迭代器 (x, y, count) ，在哪里 x 和 y 请参考像素中心的坐标。在Geoserver中，您可以使用WPS DensityProcess根据查询结果创建热图。看见热图以获取更多信息。

钥匙	类型	地球服务器转换
QueryHints.DENSITY_BBOX	`ReferencedEnvelope`	使用WPS
QueryHints.DENSITY_GEOM	细绳
QueryHints.DENSITY_WEIGHT	细绳
QueryHints.DENSITY_WIDTH	整型
QueryHints.DENSITY_HEIGHT	整型

import org.geotools.data.Transaction
import org.geotools.geometry.jts.ReferencedEnvelope
import org.geotools.referencing.CRS
import org.locationtech.geomesa.index.conf.QueryHints
import org.locationtech.geomesa.index.iterators.DensityScan

val bounds = new ReferencedEnvelope(-120.0, -110.0, 45.0, 55.0, CRS.decode("EPSG:4326"))
query.getHints.put(QueryHints.DENSITY_BBOX, bounds)
query.getHints.put(QueryHints.DENSITY_WIDTH, 500)
query.getHints.put(QueryHints.DENSITY_HEIGHT, 500)

val reader = dataStore.getFeatureReader(query, Transaction.AUTO_COMMIT)
try {
  val decode = DensityScan.decodeResult(bounds, 500, 500)
  while (reader.hasNext) {
    val pts = decode(reader.next())
    while (pts.hasNext) {
      val (x, y, weight) = pts.next()
      // do something with the cell
    }
  }
} finally {
  reader.close()
}

7.14.3. 统计查询¶

GeoMesa支持针对数据集生成各种统计数据。这些统计信息是在分布式扫描中生成的，因此提供了内置的并行性，需要的网络流量更少。支持以下统计信息：

计数
最小/最大值(边界)
值的枚举
TOP-K值
值的频率
数值直方图
descriptive statistics

在Geoserver中，您可以使用 StatsProcess 。否则，将通过以下查询提示控制查询：

钥匙	类型	地球服务器转换
QueryHints.STATS_STRING	细绳	使用WPS
QueryHints.ENCODE_STATS	布尔型(可选)	使用WPS

import org.geotools.data.Transaction
import org.locationtech.geomesa.index.conf.QueryHints
import org.locationtech.geomesa.index.iterators.StatsScan
import org.locationtech.geomesa.utils.stats.Stat

query.getHints.put(QueryHints.STATS_STRING, "Count()")
query.getHints.put(QueryHints.ENCODE_STATS, java.lang.Boolean.TRUE)

val reader = dataStore.getFeatureReader(query, Transaction.AUTO_COMMIT)

val result: Stat = try {
  // stats should always return exactly one result, even if there are no features in the table
  StatsScan.decodeStat(sft)(reader.next.getAttribute(0).asInstanceOf[String])
} finally {
  reader.close()
}

看见分析命令有关通过GeoMesa命令行工具运行统计查询的信息。

7.14.3.1. 对提示的解释¶

7.14.3.1.1. STATS_STRING¶

此提示是描述要收集的统计信息的字符串。每种类型的STAT都有相应的字符串表示。通过使用分号分隔，可以一次收集多个统计信息。中提供了一些方便的方法，而不是手动构造统计字符串 org.locationtech.geomesa.utils.stats.Stat 这将生成有效的统计字符串。可以通过尝试使用以下命令解析统计信息字符串来对其进行验证 org.locationtech.geomesa.utils.stats.Stat.apply 。实现类包含在包中 org.locationtech.geomesa.utils.stats 。

统计字符串如下：

类型	实施	表示法
计数	CountStat	`Count()`
最小/最大	MinMax	`MinMax("foo")`
枚举	EnumerationStat	`Enumeration("foo")`
TOP-K	TOPK	`TopK("foo")`
频率，频率	频率	`Frequency("foo",<precision>)`
频率(按时间段)	频率	`Frequency("foo","dtg",<time period>,<precision>)`
Z3频率	Z3频率	`Z3Frequency("geom","dtg",<time period>,<precision>)`
直方图	直方图	`Histogram("foo",<bins>,<min>,<max>)`
Z3直方图	Z3组织图	`Z3Histogram("geom","dtg",<time period>,<bins>)`
描述性统计	DescriptiveStats	`DescriptiveStats("foo","bar")`
多个统计数据	SeqStat	`Count();MinMax("foo")`
分组统计信息	GroupBy	`GroupBy("foo",MinMax("bar"))`

如上表所示，可以通过分号分隔一次计算多个统计数据。此外，可以使用以下命令对分组的值计算统计信息 GroupBy 在嵌套的Stat表达式上。

Z3频率和直方图是特殊的统计信息，将对从几何图形和日期创建的Z3值进行操作。

<time period> 可以是以下之一 day ， week ， month ，或 year ，并指示应如何对数据进行分组。

这个 <precision> 频率的定义为：

对于几何和Z3类型，它是要保留的z索引的位数(最大值为64)。请注意，前2位不包含任何信息
对于日期类型，它是分组以进行装箱的毫秒数
对于数字类型，它是分组在一起的位数
对于浮点类型，它是要考虑的小数位数
对于字符串类型，它是要考虑的字符数

这个 <bins> 对于直方图，指出应该进行多少分组。这个 <min> 和 <max> 值设置分组的初始大小，但不是硬限制。如果需要，直方图将随着新值的添加而扩展，但可能会丢失一些精度。

7.14.3.1.2. ENCODE_STATS¶

该提示控制Stat是作为序列化(编码)对象返回，还是作为JSON字符串返回。序列化的统计信息可以使用 org.locationtech.geomesa.utils.stats.StatSerializer ，通过其工厂获得 apply 方法。

7.14.3.2. 通过GeoMesa API访问统计数据¶

除了通过GeoTools API进行查询外，还可以通过GeoMesa API直接访问统计数据。大多数GeoMesa数据存储区实施 org.locationtech.geomesa.index.stats.HasGeoMesaStats ，它定义了单个方法：：

def stats: org.locationtech.geomesa.index.stats.GeoMesaStats

除了运行查询外， GeoMesaStats 接口可用于检索缓存的统计信息。看见配置缓存的统计信息有关配置缓存统计信息的详细信息，请参阅。

7.14.4. 箭头编码¶

GeoMesa支持将要素返回为 Apache Arrow 编码后的矢量。这提供了优化的列式内存布局，以实现快速处理和与其他系统的互操作性。

Arrow查询的结果将是SimpleFeature的迭代器，其中每个迭代器的第一个属性将是一个字节数组。连接在一起的字节数组将形成一个Arrow文件，采用Arrow流格式(即无页脚)。

在Geoserver中，您可以使用 ArrowConversionProcess ，或通过WFS设置 outputFormat=application/vnd.arrow 并通过 format_options 参数，例如 format_options=includeFids:true;batchSize:1000 。否则，通过以下查询提示控制编码：

钥匙	类型	Geoserver格式选项
QueryHints.ARROW_ENCODE	布尔型	outputFormat=application/vnd.arrow
QueryHints.ARROW_INCLUDE_FID	布尔型(可选)	包含文件
QueryHints.ARROW_PROXY_FID	布尔型(可选)	ProxyFids
QueryHints.ARROW_SORT_FIELD	字符串(可选)	排序字段
QueryHints.ARROW_SORT_REVERSE	布尔型(可选)	排序反向
QueryHints.ARROW_DICTIONARY_FIELDS	字符串(可选)	词典字段
QueryHints.ARROW_BATCH_SIZE	整数(可选)	BatchSize
QueryHints.ARROW_FORMAT_VERSION	字符串(可选)	格式版本
QueryHints.ARROW_PROCESS_DELTAS	布尔型(可选)	进程增量

7.14.4.1. 对提示的解释¶

7.14.4.1.1. ARROW_ENCODE¶

此提示用于触发Arrow查询。

7.14.4.1.2. ARROW_INCLUDE_FID¶

此提示控制是否将特征ID作为箭头向量包括在内。默认情况下，将其包括在内。

7.14.4.1.3. ARROW_PROXY_FID¶

此提示控制是返回完整的功能ID，还是返回4字节的代理ID。通过使用 proxyID() CQL滤波功能。

7.14.4.1.4. ARROW_SORT_FIELD¶

此提示允许按特定属性对结果进行排序。仅支持属性名称，不支持任意CQL。

7.14.4.1.5. ARROW_SORT_REVERSE¶

此提示用于将排序顺序从正常(升序)反转为反向(降序)。

7.14.4.1.6. ARROW_DICTIONARY_FIELDS¶

此提示指示应对哪些简单要素属性进行字典编码。它应该是逗号分隔的属性名称列表。

7.14.4.1.7. ARROW_BATCH_SIZE¶

此提示将限制每个Arrow记录批次中包含的功能数量。Arrow文件包含一系列记录批次-限制每个批次的最大大小可以允许内存受限的系统更轻松地操作。

7.14.4.1.8. ARROW_FORMAT_VERSION¶

此提示控制Arrow二进制编码的IPC格式版本。应为有效的Arrow格式版本，即 0.16 或 0.10 。Arrow IPC格式从版本开始略有更改 0.15 。

7.14.4.1.9. ARROW_PROCESS_DELTAS¶

这是一个高级提示，可用于禁用对Arrow查询的正常处理。当设置为FALSE时，数据将以自定义二进制格式返回，并且需要先进行处理，然后才能由标准Arrow库读取。当返回未经处理的数据时，数据可以立即开始流回客户端。

7.14.4.2. 示例查询¶

import java.io.ByteArrayOutputStream
import org.geotools.data.Transaction
import org.locationtech.geomesa.index.conf.QueryHints

query.getHints.put(QueryHints.ARROW_ENCODE, java.lang.Boolean.TRUE)

val reader = dataStore.getFeatureReader(query, Transaction.AUTO_COMMIT)
val os = new ByteArrayOutputStream()

while (reader.hasNext) {
  os.write(reader.next().getAttribute(0).asInstanceOf[Array[Byte]])
}
reader.close()

// use ArrowStreamReader or other Arrow libraries to process bytes

7.14.5. 二进制编码¶

GeoMesa支持以自定义二进制格式(称为BIN)返回要素，每个要素使用16或24个字节。这提供了几个关键属性的极其紧凑的表示。

16字节的BIN格式如下：

<4 byte int><4 byte int><4 byte floating point><4 byte floating point>

第一个整数称为轨迹ID，通常用于对相关点进行分组。例如，一个行字符串可以被转换成具有公共磁道ID的几个BIN记录。第二个整数是表示自Java纪元(1970年1月1日)以来的秒数的日期。这两个浮点数分别表示记录的纬度和经度。

24字节的BIN格式与16字节版本相同，但末尾增加了8个字节用于任意数据。

BIN查询的结果将是SimpleFeature的迭代器，每个迭代器的第一个属性将是一个字节数组，其中包含一个或多个BIN编码的特征。

在Geoserver中，您可以使用 BinConversionProcess 。否则，通过以下查询提示控制编码：

钥匙	类型	地球服务器转换
QueryHints.BIN_TRACK	细绳	使用WPS
QueryHints.BIN_GEOM	字符串(可选)
QueryHints.BIN_DTG	字符串(可选)
QueryHints.BIN_LABEL	字符串(可选)
QueryHints.BIN_SORT	布尔型(可选)
QueryHints.BIN_BATCH_SIZE	整数(可选)

7.14.5.1. 对提示的解释¶

7.14.5.1.1. BIN_TRACK¶

此提示用于触发BIN查询。它应该是将用于生成每个记录的曲目ID的属性的名称。

7.14.5.1.2. BIN_GEOM¶

此提示控制用于每条记录的几何属性。如果省略，则使用特征类型的默认几何图形。

7.14.5.1.3. BIN_DTG¶

此提示控制用于每条记录的日期属性。如果省略，则使用要素类型的默认日期。

7.14.5.1.4. BIN_LABEL¶

该提示将触发24字节记录的创建，而不是标准的16字节。它应该是将用于为每条记录生成标签的属性的名称。

7.14.5.1.5. BIN_SORT¶

此提示将导致对记录进行排序。它应该是要素类型中的属性的名称。

7.14.5.1.6. BIN_BATCH_SIZE¶

此提示控制生成BIN记录时使用的批次大小。

7.14.5.2. 示例查询¶

import java.io.ByteArrayOutputStream
import org.geotools.data.Transaction
import org.locationtech.geomesa.index.conf.QueryHints

query.getHints.put(QueryHints.BIN_TRACK, "name")

val reader = dataStore.getFeatureReader(query, Transaction.AUTO_COMMIT)
val os = new ByteArrayOutputStream()

while (reader.hasNext) {
  os.write(reader.next().getAttribute(0).asInstanceOf[Array[Byte]])
}
reader.close()

// process bytes appropriately