{"_id":"56e1cdd892bf640e00b5564b","category":{"_id":"56e1ccc4e416450e00b9e48c","project":"55faeacad0e22017005b8265","version":"55faeacad0e22017005b8268","pages":["56e1cdd892bf640e00b5564b","56e1cdfde416450e00b9e490","56e1ce4892bf640e00b5564e","56e1ce81e416450e00b9e494","56e1ceebe416450e00b9e497","56e1cf39cd6a8d0e00d12176","56e30b4b51857d0e008e77a3","56e30bd26e602e0e00700b16","56e30dd0d46bc30e007bb986","56e30e3d872bb20e0051ba39","56e30f91cb6ef20e0084f23c"],"__v":11,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-03-10T19:36:36.026Z","from_sync":false,"order":18,"slug":"aggregations-facets-vector-services-guide","title":"Aggregations & Facets Vector Services Guide"},"__v":6,"project":"55faeacad0e22017005b8265","parentDoc":null,"user":"56267741db1eda0d001c3dbb","version":{"_id":"55faeacad0e22017005b8268","project":"55faeacad0e22017005b8265","__v":33,"createdAt":"2015-09-17T16:31:06.800Z","releaseDate":"2015-09-17T16:31:06.800Z","categories":["55faeacbd0e22017005b8269","55faf550764f50210095078e","55faf5b5626c341700fd9e96","55faf8a7825d5f19001fa386","560052f91503430d007cc88f","560054f73aa0520d00da0b1a","56005aaf6932a00d00ba7c62","56005c273aa0520d00da0b3f","5601ae7681a9670d006d164d","5601ae926811d00d00ceb487","5601aeb064866b1900f4768d","5601aee850ee460d0002224c","5601afa02499c119000faf19","5601afd381a9670d006d1652","561d4c78281aec0d00eb27b6","561d588d8ca8b90d00210219","563a5f934cc3621900ac278c","5665c5763889610d0008a29e","566710a36819320d000c2e93","56ddf6df8a5ae10e008e3926","56e1c96b2506700e00de6e83","56e1ccc4e416450e00b9e48c","56e1ccdfe63f910e00e59870","56e1cd10bc46be0e002af26a","56e1cd21e416450e00b9e48e","56e3139a51857d0e008e77be","573b4f62ef164e2900a2b881","57c9d1335fd8ca0e006308ed","57e2bd9d1e7b7220000d7fa5","57f2b992ac30911900c7c2b6","58adb5c275df0f1b001ed59b","58c81b5c6dc7140f003c3c46","595412446ed4d9001b3e7b37"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"v1","version_clean":"1.0.0","version":"1"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-10T19:41:12.595Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Aggregations Overview\"\n}\n[/block]\nVectorServices provides aggregation capabilities to allow users to quickly and easily summarize data based on multiple parameters.  Data can be grouped by geohash, date/time, terms, and a number of other aggregation types\n\nAggregations are useful for discovering relationships and differences among groups of data.  For example, a user could discover the most prolific Twitter users over a set of geohash boxes for the last week by aggregating tweet data by geohash region, time range, and the Twitter user name field.  Mixing different aggregation types will give users different views on their data, allowing them to discover relationships they might not have otherwise seen. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Aggregation API Parameters\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Data Type\",\n    \"h-2\": \"Parameter Type\",\n    \"h-3\": \"Definition\",\n    \"0-0\": \"aggs\",\n    \"1-0\": \"query\",\n    \"2-0\": \"left\",\n    \"3-0\": \"right\",\n    \"4-0\": \"upper\",\n    \"5-0\": \"lower\",\n    \"6-0\": \"startDate\",\n    \"7-0\": \"endDate\",\n    \"8-0\": \"count\",\n    \"0-1\": \"String\",\n    \"1-1\": \"String\",\n    \"2-1\": \"String\",\n    \"3-1\": \"String\",\n    \"4-1\": \"String\",\n    \"5-1\": \"String\",\n    \"6-1\": \"String\",\n    \"7-1\": \"String\",\n    \"8-1\": \"String\",\n    \"0-2\": \"Query\",\n    \"1-2\": \"Query\",\n    \"2-2\": \"Query\",\n    \"3-2\": \"Query\",\n    \"4-2\": \"Query\",\n    \"5-2\": \"Query\",\n    \"6-2\": \"Query\",\n    \"7-2\": \"Query\",\n    \"8-2\": \"Query\",\n    \"0-3\": \"(required) The aggregation definitions (see below for more detail)\",\n    \"1-3\": \"(optional) The Elasticsearch query string to filter the source items for the aggregations.  See [Query Syntax, Fields, and Type Suffixes](doc:vector-query-syntax-query-fields-and-type-suffixes) for more detail.\",\n    \"2-3\": \"(required for bounding box aggregations) The leftmost X-coordinate for the bounding box\",\n    \"3-3\": \"(required for bounding box aggregations) The rightmost X-coordinate for the bounding box\",\n    \"4-3\": \"(required for bounding box aggregations) The highest Y-coordinate for the bounding box\",\n    \"5-3\": \"(required for bounding box aggregations) The lowest Y-coordinate for the bounding box\",\n    \"6-3\": \"(optional, required with 'endDate') A convenience parameter for setting the value for the earliest item_date value to be included in the set of aggregated items.  Note: The date range can be specified with ISO-8601 date strings or with expressions using the term \\\"now\\\" to indicate the current date. The date expressions can include simple \\\"date math\\\" by appending \\\"+\\\" or \\\"-\\\" along with a numeral and a unit. For example, to set the start date to one day ago, the start date expression would read \\\"now-1d\\\". The units supported are \\\"y\\\" (year), \\\"M\\\" (month), \\\"w\\\" (week), \\\"d\\\" (day), \\\"h\\\" (hour), \\\"m\\\" (minute), and \\\"s\\\" (second). The date range is inclusive at both ends. If no date range is provided, then all items within the AOI will be included.\",\n    \"7-3\": \"(optional,required with 'startDate') A convenience parameter for setting the value for the latest item_date value to be included in the set of aggregated items.  Note: The date range can be specified with ISO-8601 date strings or with expressions using the term \\\"now\\\" to indicate the current date. The date expressions can include simple \\\"date math\\\" by appending \\\"+\\\" or \\\"-\\\" along with a numeral and a unit. For example, to set the start date to one day ago, the start date expression would read \\\"now-1d\\\". The units supported are \\\"y\\\" (year), \\\"M\\\" (month), \\\"w\\\" (week), \\\"d\\\" (day), \\\"h\\\" (hour), \\\"m\\\" (minute), and \\\"s\\\" (second). The date range is inclusive at both ends. If no date range is provided, then all items within the AOI will be included.\",\n    \"8-3\": \"(optional) The number of groupings to return per aggregation, used to display the top N buckets for an aggregation. Default 10.\"\n  },\n  \"cols\": 4,\n  \"rows\": 9\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Aggregation Type Definitions\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Aggregation Query\",\n    \"h-1\": \"Definition\",\n    \"0-0\": \"geohash\",\n    \"1-0\": \"date_hist\",\n    \"2-0\": \"terms\",\n    \"3-0\": \"avg\",\n    \"4-0\": \"cardinality\",\n    \"5-0\": \"avg_geo_lat\",\n    \"6-0\": \"avg_geo_lon\",\n    \"6-1\": \"Computes the average longitude of the point_samples field for a set of documents\",\n    \"5-1\": \"Computes the average latitude of the point_samples field for a set of documents\",\n    \"4-1\": \"Computes the number of unique values for the document field specified.  The field definition is required.\\nFor example\\nTo compute the number of unique values for the ingest_source field, use “cardinality:ingest_source”.\",\n    \"3-1\": \"Computes the average of the values for the document field.  The field definition is required.\\nFor example:\\nTo compute the average for the “positive sentiment” attribute value, use “avg:attributes.sentiment_positive_dbl”.\\nNote: When using attributes, be sure to use the numeric version of the attribute, e.g. the attribute that ends with either “_int” or “_dbl”.\",\n    \"2-1\": \"Counts the set of documents into buckets based on the unique values of the document field specified in the aggregation definition.  The field definition is required.\\nFor example:\\nTo count documents into buckets based on unique terms in the ingest_source field, use “terms:ingest_source”.\",\n    \"1-1\": \"Counts the set of documents into buckets based on the item_date field. An optional interval may be added to the aggregation definition to change the time unit for each bucket. The units supported are “y” (year), “M” (month), “w” (week), “d” (day), “h” (hour), “m”  (minute), and “s” (second).\\nFor example:\\nTo bucket a set of documents by minute, use “date_hist:m”. The default unit is “d” (“date_hist:d”).\",\n    \"0-1\": \"Counts the set of documents into buckets based on the geohash of the point_samples field. An optional precision may be added to the aggregation definition to change the length of the geohash for each bucket.\\nFor example:\\nTo bucket a set of documents by four-character geohashes, use “geohash:4”. The default precision is six characters (“geohash:6”).\"\n  },\n  \"cols\": 2,\n  \"rows\": 7\n}\n[/block]\n**Note:** aggregations can be nested within each other by creating a sequence of aggregation definitions separated by semi-colons.  A final “grouping” of aggregations can be at the bottom level by surrounding the final set of aggregations with parentheses and separating them by commas.  For example, to group a set of documents by geohash, time range, and finally to count the total number of terms in and list the most highly-occurring values for the ingest_source field in those groups, the 'aggs' definition might look like this: ```geohash:4;date_hist:d;(cardinality:ingest_source,terms:ingest_source)```\n\n**Note:** query aggregations can be made using either a bounding box to reference the aoi, or using polygons for a more precise aoi/multiple aois.  For a bounding box, use the GET method with the upper/lower X/Y parameters.  For an arbitary polygon, use the POST method with a GeoJSON-formatted polygon definition in the body of the request.\n\n**For more information** on querying and query construction, check the [Query Syntax, Fields, and Type Suffixes](doc:vector-query-syntax-query-fields-and-type-suffixes) page and [Vector Services Example Query Constructions](doc:vs-example-query-constructions) page.\n\n<h2>Associated API calls</h2>\n[Query](doc:aggs-query)\n[Shape Query](doc:aggs-shape-query)","excerpt":"Overview of the Aggregations API.","slug":"aggregations-course","type":"basic","title":"Aggregations Course"}

Aggregations Course

Overview of the Aggregations API.

[block:api-header] { "type": "basic", "title": "Aggregations Overview" } [/block] VectorServices provides aggregation capabilities to allow users to quickly and easily summarize data based on multiple parameters. Data can be grouped by geohash, date/time, terms, and a number of other aggregation types Aggregations are useful for discovering relationships and differences among groups of data. For example, a user could discover the most prolific Twitter users over a set of geohash boxes for the last week by aggregating tweet data by geohash region, time range, and the Twitter user name field. Mixing different aggregation types will give users different views on their data, allowing them to discover relationships they might not have otherwise seen. [block:api-header] { "type": "basic", "title": "Aggregation API Parameters" } [/block] [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Data Type", "h-2": "Parameter Type", "h-3": "Definition", "0-0": "aggs", "1-0": "query", "2-0": "left", "3-0": "right", "4-0": "upper", "5-0": "lower", "6-0": "startDate", "7-0": "endDate", "8-0": "count", "0-1": "String", "1-1": "String", "2-1": "String", "3-1": "String", "4-1": "String", "5-1": "String", "6-1": "String", "7-1": "String", "8-1": "String", "0-2": "Query", "1-2": "Query", "2-2": "Query", "3-2": "Query", "4-2": "Query", "5-2": "Query", "6-2": "Query", "7-2": "Query", "8-2": "Query", "0-3": "(required) The aggregation definitions (see below for more detail)", "1-3": "(optional) The Elasticsearch query string to filter the source items for the aggregations. See [Query Syntax, Fields, and Type Suffixes](doc:vector-query-syntax-query-fields-and-type-suffixes) for more detail.", "2-3": "(required for bounding box aggregations) The leftmost X-coordinate for the bounding box", "3-3": "(required for bounding box aggregations) The rightmost X-coordinate for the bounding box", "4-3": "(required for bounding box aggregations) The highest Y-coordinate for the bounding box", "5-3": "(required for bounding box aggregations) The lowest Y-coordinate for the bounding box", "6-3": "(optional, required with 'endDate') A convenience parameter for setting the value for the earliest item_date value to be included in the set of aggregated items. Note: The date range can be specified with ISO-8601 date strings or with expressions using the term \"now\" to indicate the current date. The date expressions can include simple \"date math\" by appending \"+\" or \"-\" along with a numeral and a unit. For example, to set the start date to one day ago, the start date expression would read \"now-1d\". The units supported are \"y\" (year), \"M\" (month), \"w\" (week), \"d\" (day), \"h\" (hour), \"m\" (minute), and \"s\" (second). The date range is inclusive at both ends. If no date range is provided, then all items within the AOI will be included.", "7-3": "(optional,required with 'startDate') A convenience parameter for setting the value for the latest item_date value to be included in the set of aggregated items. Note: The date range can be specified with ISO-8601 date strings or with expressions using the term \"now\" to indicate the current date. The date expressions can include simple \"date math\" by appending \"+\" or \"-\" along with a numeral and a unit. For example, to set the start date to one day ago, the start date expression would read \"now-1d\". The units supported are \"y\" (year), \"M\" (month), \"w\" (week), \"d\" (day), \"h\" (hour), \"m\" (minute), and \"s\" (second). The date range is inclusive at both ends. If no date range is provided, then all items within the AOI will be included.", "8-3": "(optional) The number of groupings to return per aggregation, used to display the top N buckets for an aggregation. Default 10." }, "cols": 4, "rows": 9 } [/block] [block:api-header] { "type": "basic", "title": "Aggregation Type Definitions" } [/block] [block:parameters] { "data": { "h-0": "Aggregation Query", "h-1": "Definition", "0-0": "geohash", "1-0": "date_hist", "2-0": "terms", "3-0": "avg", "4-0": "cardinality", "5-0": "avg_geo_lat", "6-0": "avg_geo_lon", "6-1": "Computes the average longitude of the point_samples field for a set of documents", "5-1": "Computes the average latitude of the point_samples field for a set of documents", "4-1": "Computes the number of unique values for the document field specified. The field definition is required.\nFor example\nTo compute the number of unique values for the ingest_source field, use “cardinality:ingest_source”.", "3-1": "Computes the average of the values for the document field. The field definition is required.\nFor example:\nTo compute the average for the “positive sentiment” attribute value, use “avg:attributes.sentiment_positive_dbl”.\nNote: When using attributes, be sure to use the numeric version of the attribute, e.g. the attribute that ends with either “_int” or “_dbl”.", "2-1": "Counts the set of documents into buckets based on the unique values of the document field specified in the aggregation definition. The field definition is required.\nFor example:\nTo count documents into buckets based on unique terms in the ingest_source field, use “terms:ingest_source”.", "1-1": "Counts the set of documents into buckets based on the item_date field. An optional interval may be added to the aggregation definition to change the time unit for each bucket. The units supported are “y” (year), “M” (month), “w” (week), “d” (day), “h” (hour), “m” (minute), and “s” (second).\nFor example:\nTo bucket a set of documents by minute, use “date_hist:m”. The default unit is “d” (“date_hist:d”).", "0-1": "Counts the set of documents into buckets based on the geohash of the point_samples field. An optional precision may be added to the aggregation definition to change the length of the geohash for each bucket.\nFor example:\nTo bucket a set of documents by four-character geohashes, use “geohash:4”. The default precision is six characters (“geohash:6”)." }, "cols": 2, "rows": 7 } [/block] **Note:** aggregations can be nested within each other by creating a sequence of aggregation definitions separated by semi-colons. A final “grouping” of aggregations can be at the bottom level by surrounding the final set of aggregations with parentheses and separating them by commas. For example, to group a set of documents by geohash, time range, and finally to count the total number of terms in and list the most highly-occurring values for the ingest_source field in those groups, the 'aggs' definition might look like this: ```geohash:4;date_hist:d;(cardinality:ingest_source,terms:ingest_source)``` **Note:** query aggregations can be made using either a bounding box to reference the aoi, or using polygons for a more precise aoi/multiple aois. For a bounding box, use the GET method with the upper/lower X/Y parameters. For an arbitary polygon, use the POST method with a GeoJSON-formatted polygon definition in the body of the request. **For more information** on querying and query construction, check the [Query Syntax, Fields, and Type Suffixes](doc:vector-query-syntax-query-fields-and-type-suffixes) page and [Vector Services Example Query Constructions](doc:vs-example-query-constructions) page. <h2>Associated API calls</h2> [Query](doc:aggs-query) [Shape Query](doc:aggs-shape-query)