From a253c51310bb525b2c9822b3af41d4806e5b53aa Mon Sep 17 00:00:00 2001
From: Mike Farah <mikefarah@gmail.com>
Date: Thu, 10 Mar 2022 13:50:03 +1100
Subject: [PATCH] v4.22.1

---
 operators/pick.md   | 53 +++++++++++++++++++++++++++++++++++++++++++++
 usage/properties.md | 13 -----------
 2 files changed, 53 insertions(+), 13 deletions(-)
 create mode 100644 operators/pick.md

diff --git a/operators/pick.md b/operators/pick.md
new file mode 100644
index 00000000..b93bf04f
--- /dev/null
+++ b/operators/pick.md
@@ -0,0 +1,53 @@
+# Pick
+
+Filter a map by the specified list of keys. Map is returned with the key in the order of the pick list.
+
+Similarly, filter an array by the specified list of indices.
+
+{% hint style="warning" %}
+Note that versions prior to 4.18 require the 'eval/e' command to be specified.&#x20;
+
+`yq e <exp> <file>`
+{% endhint %}
+
+## Pick keys from map
+Note that the order of the keys matches the pick order and non existent keys are skipped.
+
+Given a sample.yml file of:
+```yaml
+myMap:
+  cat: meow
+  dog: bark
+  thing: hamster
+  hamster: squeek
+```
+then
+```bash
+yq '.myMap |= pick(["hamster", "cat", "goat"])' sample.yml
+```
+will output
+```yaml
+myMap:
+  hamster: squeek
+  cat: meow
+```
+
+## Pick indices from array
+Note that the order of the indexes matches the pick order and non existent indexes are skipped.
+
+Given a sample.yml file of:
+```yaml
+- cat
+- leopard
+- lion
+```
+then
+```bash
+yq 'pick([2, 0, 734, -5])' sample.yml
+```
+will output
+```yaml
+- lion
+- cat
+```
+
diff --git a/usage/properties.md b/usage/properties.md
index d5477434..97d05760 100644
--- a/usage/properties.md
+++ b/usage/properties.md
@@ -144,16 +144,3 @@ person.pets.0 = dog
 person.food.0 = pizza
 ```
 
-## Empty doc
-Given a sample.properties file of:
-```properties
-
-```
-then
-```bash
-yq -p=props sample.properties
-```
-will output
-```yaml
-```
-