PIG-5023: Documentation for BagToTuple (icook via knoguchi)
git-svn-id: https://svn.apache.org/repos/asf/pig/trunk@1759504 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/CHANGES.txt b/CHANGES.txt
index e9b4af3..5574f37 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -24,6 +24,8 @@
IMPROVEMENTS
+PIG-5023: Documentation for BagToTuple (icook via knoguchi)
+
PIG-5022: Error in TOKENIZE Example (icook vi knoguchi)
PIG-4931: Document IN operator (dbist13 vi daijy)
diff --git a/src/docs/src/documentation/content/xdocs/func.xml b/src/docs/src/documentation/content/xdocs/func.xml
index 34bce7c..d792a2a 100644
--- a/src/docs/src/documentation/content/xdocs/func.xml
+++ b/src/docs/src/documentation/content/xdocs/func.xml
@@ -294,6 +294,75 @@
</section>
</section>
+<section id="bagtotuple">
+ <title>BagToTuple</title>
+ <p>Un-nests the elements of a bag into a tuple.</p>
+
+ <section>
+ <title>Syntax</title>
+ <table>
+ <tr>
+ <td>
+ <p>BagToTuple(expression)</p>
+ </td>
+ </tr>
+ </table></section>
+
+ <section>
+ <title>Terms</title>
+ <table>
+ <tr>
+ <td>
+ <p>expression</p>
+ </td>
+ <td>
+ <p>An expression with data type bag.</p>
+ </td>
+ </tr>
+ </table>
+ </section>
+
+ <section>
+ <title>Usage</title>
+ <p>BagToTuple creates a tuple from the elements of a bag. It removes only
+ the first level of nesting; it does not recursively un-nest nested bags.
+ Unlike FLATTEN, BagToTuple will not generate multiple output records per
+ input record.
+ </p>
+ </section>
+ <section>
+ <title>Examples</title>
+ <p>In this example, a bag containing tuples with one field is converted to a tuple.</p>
+<source>
+A = LOAD 'bag_data' AS (B1:bag{T1:tuple(f1:chararray)});
+
+DUMP A;
+({('a'),('b'),('c')})
+({('d'),('e'),('f')})
+
+X = FOREACH A GENERATE BagToTuple(B1);
+
+DUMP X;
+(('a','b','c'))
+(('d','e','f'))
+</source>
+ <p>In this example, a bag containing tuples with two fields is converted to a tuple.</p>
+<source>
+A = LOAD 'bag_data' AS (B1:bag{T1:tuple(f1:int,f2:int)});
+
+DUMP A;
+({(4,1),(7,8),(4,9)})
+({(5,8),(4,3),(3,8)})
+
+X = FOREACH A GENERATE BagToTuple(B1);
+
+DUMP X;
+((4,1,7,8,4,9))
+((5,8,4,3,3,8))
+</source>
+ </section>
+</section>
+
<section id="bloom">
<title>Bloom</title>
<p>Bloom filters are a common way to select a limited set of records before
diff --git a/src/docs/src/documentation/content/xdocs/pig-index.xml b/src/docs/src/documentation/content/xdocs/pig-index.xml
index 5027f53..2ca63a3 100644
--- a/src/docs/src/documentation/content/xdocs/pig-index.xml
+++ b/src/docs/src/documentation/content/xdocs/pig-index.xml
@@ -137,12 +137,15 @@
<br></br> <a href="func.html#tobag">and TOBAG function</a>
<br></br> <a href="basic.html#type-construction">and type construction operators</a>
<br></br> <a href="func.html#bagtostring">converting to string</a>
+<br></br> <a href="func.html#bagtotuple">converting to tuple</a>
<br></br> <a href="basic.html#schema-multi">schemas for multiple types</a>
<br></br> <a href="basic.html#bag">syntax</a>
</p>
<p><a href="func.html#bagtostring">BagToString</a> function</p>
+<p><a href="func.html#bagtotuple">BagToTuple</a> function</p>
+
<p><a href="start.html#batch-mode">batch mode</a>. <em>See also</em> memory management</p>
<p><a href="basic.html#arithmetic">bincond operator</a> ( ?: )</p>
