[DOCS] Document List.Get and the new deep query

docs/structs.md

@@ -41,3 +41,52 @@ can be referenced by ID or name. The `1` is a string because JSON only allows
 keys to be strings.
 
 
+## Using Lists
+
+Given a List of something, you can use it just like a normal list.
+
+```capnp
+struct Person {
+  ...
+  addresses @2 :List(Text);
+}
+```
+A `List` of `Text` acts exactly like a list of (unicode) strings.
+
+```python
+p = Person()
+p.addresses.append('address #1')
+json.dumps(p) == '{"addresses": ["address #1"]}'
+```
+
+The cool part of `List`s come in when it's a `List` of structs.
+
+```capnp
+struct USAddress {
+  lines :group {
+    line1 @0 :Text;
+    line2 @1 :Text;
+  }
+  state @2 :Text;
+  ...
+}
+
+struct Person {
+  addresses @2 :List(USAddress);
+}
+```
+
+Now, we can do something interesting by getting the first element in the list
+that matches our query.
+
+```python
+p = Person({'addresses': [
+    {'lines': {'line1': '1 Main St'}, 'state': 'NY'},
+    {'state': 'CA'},
+]})
+# Returns the second address.
+p.addresses.Get(state=CA)
+# This returns the first address, not just the line or lines.
+p.addresses.Get(lines__line1='1 Main St').state == 'NY'
+```
+