The Stream/Document Boundary
The examples so far have used an EMML statement to load the data as a stream, used RAQL extension statements to query the stream and then returned the query results as the mashup results. Currently, however, mashups cannot return streams as their results. As the following figure shows, streams must be converted to a document before being returned from the mashup.
You must also convert query result streams to documents to use EMML statements that are not RAQL extensions with query results. Any EMML statement that uses XPath expressions requires that the stream first be converted to a document.
Note: | Because of the volume of data, it is a good practice to avoid using the <display> statement with RAQL query results. |
The <raql> statements used in earlier examples implicitly converted the query results to a document-type variable by using result as the output variable and not setting the streaming mode. You can have query results returned in a stream, when needed, by setting the stream attribute on the RAQL query. For example:
<!-- performs query and returns results as a stream -->
<raql outputvariable="$queryresult" stream="true" >
select firstname, lastname, state, chamber, party, gender
from congress where chamber='Senate'
</raql>
In general, if a mashup statement or the receiving variable does not set stream='true', then the dataset will be treated as a document not a stream.
