Merge branch 'master' into meyskens-patch-1

Author: ajnavarro

docs/using-gitbase/examples.md

@@ -181,13 +181,13 @@ or through a specific property:
 SELECT file_path, uast_extract(uast(blob_content, language(file_path), "//FuncLit"), "internalRole") FROM files;
 ```
 
-As result, you will get an array of arrays showing a list of the retrieved information for each of the given nodes:
+As result, you will get an array showing a list of the retrieved information. Each element in the list matches a node in the given sequence of nodes having a value for that property. It means that the length of the properties list may not be equal to the length of the given sequence of nodes:
 
 ```sh
 +-------------------+------------------------------------------------------------------------------------------------+
 | file_path         | uast_extract(uast(files.blob_content, language(files.file_path), "//FuncLit"), "internalRole") |
 +-------------------+------------------------------------------------------------------------------------------------+
-| benchmark_test.go | [["Args"],["Args"],["Args"],["Args"],["Args"],["Args"],["Args"]]                               |
+| benchmark_test.go | ["Args","Args","Args","Args","Args","Args","Args"]                                             |
 +-------------------+------------------------------------------------------------------------------------------------+
 ```
 

docs/using-gitbase/functions.md

@@ -11,12 +11,12 @@ To make some common tasks easier for the user, there are some functions to inter
 |language(path, [blob])text| gets the language of a file given its path and the optional content of the file                                    |
 |uast(blob, [lang, [xpath]]) blob| returns a sequence of serialized UAST nodes in semantic mode                                                 |
 |uast_mode(mode, blob, lang) blob| returns a sequence of serialized UAST nodes specifying its language and mode (semantic, annotated or native) |
-|uast_xpath(blob, xpath)| performs an XPath query over the given UAST nodes                                                                     |
-|uast_extract(blob, key)| extracts information identified by the given key from the uast nodes                                                  |
-|uast_children(blob)| returns a flattened array of the children UAST nodes from each one of the UAST nodes in the given sequence                |
+|uast_xpath(blob, xpath) blob| performs an XPath query over the given UAST nodes                                                                |
+|uast_extract(blob, key) text array| extracts information identified by the given key from the uast nodes                                       |
+|uast_children(blob) blob| returns a flattened array of the children UAST nodes from each one of the UAST nodes in the given sequence           |
 
 
-## Note about uast and uast_mode functions
+## Note about uast, uast_mode, uast_xpath and uast_children functions
 
 The data returned by these functions are a list of UAST nodes serialized as explained below.
 
@@ -30,6 +30,34 @@ BigEndianInt32(len(marhsal(node))+marshal(node)+
 ...
 ```
 
+## How to formulate XPath queries when use uast and uast_xpath functions
+
+Have a look at the [bblfsh docs](https://docs.sourced.tech/babelfish/using-babelfish/uast-querying) to query UASTs with XPath.
+
+## How to use uast_extract
+
+Check out the [UAST specification](https://docs.sourced.tech/babelfish/uast/uast-specification) to know what an UAST node represents.
+
+`uast_extracts` accepts special selectors to match common node properties:
+
+- `@type`
+- `@token`
+- `@role`
+- `@startpos`
+- `@endpos`
+
+Using these selectors as in,
+
+> uast_extract(nodes_column, @common_selector)
+
+you will extract the value of that property for each node.
+
+Nodes that have no value for the requested property will not be present in any way in the final array. That is, having a sequence of nodes `[node-1, node-2, node-3]` and knowing that node-2 doesn't have a value for the requested property, the returned array will be `[prop-1, prop-3]`.
+
+Also, if you want to retrieve values from a non common property, you can pass it directly
+
+> uast_extract(nodes_column, 'some-property')
+
 ## Standard functions
 
 You can check standard functions in [`go-mysql-server` documentation](https://github.com/src-d/go-mysql-server/tree/679d33772845593ce5fdf17925f49f2335bc8356#custom-functions).