Document top operator

docs/language/conventions.md

@@ -12,6 +12,7 @@ in the Zed documentation include several type classes as follows:
 * _any_ - any Zed data type
 * _float_ - any floating point Zed type
 * _int_ - any signed or unsigned Zed integer type
+* _uint_ - any unsigned Zed integer type
 * _number_ - either float or int
 * _record_ - any [record](../formats/zson.md#251-record-type) type
 

docs/language/operators/README.md

@@ -31,7 +31,7 @@ operators listed below, Zed also allows for the creation of
 * [summarize](summarize.md) -  perform aggregations
 * [switch](switch.md) -  route values based on cases
 * [tail](tail.md) - copy trailing values of input sequence
-* [top](top.md) - get top n sorted values of input sequence
+* [top](top.md) - get top N sorted values of input sequence
 * [uniq](uniq.md) - deduplicate adjacent values
 * [where](where.md) - select values based on a Boolean expression
 * [yield](yield.md) - emit values from expressions

docs/language/operators/top.md

@@ -1,22 +1,23 @@
 ### Operator
 
-  **top** — get top n sorted values of input sequence
+  **top** — get top N sorted values of input sequence
 
 ### Synopsis
 
 ```
-top <uint> <expr> [ <expr> ...]
+top <uint> <expr> [, <expr> ...]
 ```
 ### Description
 
-The `top` operator returns the top n values from a sequence sorted in descending
-order by one or more expressions. `top` is functionally similar to `sort` except
-only the top n values are stored in memory (i.e., values less than the minimum
-are discarded).
+The `top` operator returns the top N values from a sequence sorted in descending
+order by one or more expressions. `top` is functionally similar to
+[`sort`](sort.md) but is less resource intensive because only the top
+N values are stored in memory (i.e., values less than the minimum are
+discarded).
 
 ### Examples
 
-_Grab top two values from a sequence of integers
+_Grab the top two values from a sequence of integers_
 ```mdtest-command
 echo '1 5 3 9 23 7' | zq -z 'top 2 this' -
 ```
@@ -25,3 +26,15 @@ echo '1 5 3 9 23 7' | zq -z 'top 2 this' -
 23
 9
 ```
+_Find the two names most frequently referenced in a sequence of records_
+```mdtest-command
+echo '{name:"joe", age:22} {name:"bob", age:37} {name:"liz", age:25}
+      {name:"bob", age:18} {name:"liz", age:34} {name:"zoe", age:55}
+      {name:"ray", age:44} {name:"sue", age:41} {name:"liz", age:60}' |
+  zq -z 'count() by name | top 2 count' -
+```
+=>
+```mdtest-output
+{name:"liz",count:3(uint64)}
+{name:"bob",count:2(uint64)}
+```