Package org.intermine.client.services

Class QueryService

  • public class QueryService
extends AbstractQueryService<org.intermine.pathquery.PathQuery>
    The QueryService class provides a mechanism for sending data queries to an InterMine webservice, and retrieving and parsing the results.

    The basic tool for querying data in InterMine is the PathQuery object. PathQueries are highly abstracted structured representations of a query over a database, including ways to select the output columns and the filters. To see examples to see how to construct PathQuery objects, see PathQuery.

    Usage: 
         ServiceFactory services = new ServiceFactory(serviceRootUrl);
     QueryService queryService = services.getQueryService();

     PathQuery query = new PathQuery(services.getModel());
     query.addViews("Gene.symbol", "Gene.length", "Gene.proteins.primaryIdentifier");
     query.addConstraint(Constraints.lookup("Gene", "zen", "D. melanogaster"));

     //find out how many results there are
     out.printf("There are %d results for this query\n", queryService.getCount(query));

     Iterator> results = queryService.getRowListIterator(query);

     while (results.hasNext()) {
         out.println(StringUtils.join(results.next(), "\t"));
     }
    Query results are typically fetched as a multi-dimensional list of strings (rows of columns), but you can also request simply the count of result rows in the whole result set, and JSONObjects, a nested representation of individual records (@link {http://www.intermine.org/wiki/JSONObjectFormat}). Results can also be paged: passing in the start index and the page size will return the appropriate slice of results. The default start is 0 (the beginning) and the default page-size is null (everything). So the query above will get all results.

    • Constructor Detail

      • QueryService

        public QueryService​(java.lang.String rootUrl,
                    java.lang.String applicationName)
        Constructor. It is recommended for maintainability reasons that you not use this constructor. Instead, use the ServiceFactory instead for creating instances of this class.
        Parameters:
        rootUrl - root URL
        applicationName - application name

    • Method Detail

      • createPathQuery

        public org.intermine.pathquery.PathQuery createPathQuery​(java.lang.String queryXml)
        Constructs a PathQuery from its XML representation. You can use this method for creating a PathQuery, modifying it a bit and then executing it afterwards. This might be useful if you have saved some useful queries as XML to local files and wish to adjust some of their parameters in Java code.
        Parameters:
        queryXml - PathQuery represented as a XML string
        Returns:
        created PathQuery

      • getCount

        public int getCount​(org.intermine.pathquery.PathQuery query)

      • getCount

        public int getCount​(java.lang.String queryXml)
        Returns the number of results the specified query will return.
        Parameters:
        queryXml - PathQuery represented as a XML string
        Returns:
        number of results of specified query.

      • getAllJSONResults

        public java.util.List<org.json.JSONObject> getAllJSONResults​(java.lang.String queryXml)
                                                      throws org.json.JSONException
        Fetch all the results as a list of JSON Objects
        Parameters:
        queryXml - An XML string representing the query
        Returns:
        a list of JSON objects
        Throws:
        org.json.JSONException - if the server returns badly formatted JSON, or non-JSON data

      • getJSONResults

        public java.util.List<org.json.JSONObject> getJSONResults​(org.intermine.pathquery.PathQuery query,
                                                          Page page)
                                                   throws org.json.JSONException
        Throws:
        org.json.JSONException

      • getJSONResults

        public java.util.List<org.json.JSONObject> getJSONResults​(java.lang.String queryXml,
                                                          Page page)
                                                   throws org.json.JSONException
        Fetch some results as a list of JSON Objects. You define which results you want by supplying a start index, and a maximum page size.
        Parameters:
        queryXml - An XML string representing the query
        page - The subsection of the result set to retrieve.
        Returns:
        a list of JSON objects
        Throws:
        org.json.JSONException - if the server returns badly formatted JSON, or non-JSON data

      • getResults

        public java.util.List<java.util.List<java.lang.String>> getResults​(org.intermine.pathquery.PathQuery query,
                                                                   Page page)

      • getResults

        public java.util.List<java.util.List<java.lang.String>> getResults​(java.lang.String queryXml,
                                                                   Page page)
        Returns a specific set of the results of the specified PathQuery. If you expect a lot of results, or have set a very large page size we would recommend that you use the getResultIterator() method instead, as that will read through the lines one by one without storing them all in memory at once.
        Parameters:
        queryXml - PathQuery represented as a XML string""
        page - The subsection of the result set to retrieve.
        Returns:
        results of specified PathQuery

      • getAllResults

        public java.util.List<java.util.List<java.lang.String>> getAllResults​(java.lang.String queryXml)
        Returns all of the results of the specified PathQuery. If you expect a lot of results, we would recommend that you use the getResultIterator() method instead, as that will read through the lines one by one without storing them all in memory at once.
        Parameters:
        queryXml - PathQuery represented as a XML string
        Returns:
        results of specified PathQuery

      • getRowIterator

        public java.util.Iterator<java.util.List<java.lang.String>> getRowIterator​(org.intermine.pathquery.PathQuery query,
                                                                           Page page)

      • getRowIterator

        public java.util.Iterator<java.util.List<java.lang.String>> getRowIterator​(java.lang.String queryXml,
                                                                           Page page)
        Returns a specific set of the results of a specified PathQuery as an iterator. We would recommend that you use this method if you expect a lot of rows of results and might run out of memory.
        Parameters:
        queryXml - the query represented as an XML string
        page - The subsection of the result set to retrieve.
        Returns:
        results of specified PathQuery

      • getAllRowIterator

        public java.util.Iterator<java.util.List<java.lang.String>> getAllRowIterator​(java.lang.String queryXml)
        Returns all the results of a specified PathQuery as an iterator. We would recommend that you use this method if you expect a lot of rows of results and might run out of memory.
        Parameters:
        queryXml - the query represented as an XML string
        Returns:
        an iterator over the results of the specified PathQuery

      • getRowsAsLists

        public java.util.List<java.util.List<java.lang.Object>> getRowsAsLists​(java.lang.String query,
                                                                       Page page)
        Get results for a query as rows of objects.
        Parameters:
        query - The query to run.
        page - The subsection of the result set to retrieve.
        Returns:
        a list of rows, which are each a list of cells.

      • getRowsAsLists

        public java.util.List<java.util.List<java.lang.Object>> getRowsAsLists​(java.lang.String query)
        Get results for a query as rows of objects. Retrieve up to 10,000,000 rows from the beginning.
        Parameters:
        query - The query to run.
        Returns:
        a list of rows, which are each a list of cells.

      • getRowsAsMaps

        public java.util.List<java.util.Map<java.lang.String,​java.lang.Object>> getRowsAsMaps​(java.lang.String query,
                                                                                            Page page)
        Get results for a query as rows of objects.
        Parameters:
        query - The query to run.
        page - The subsection of the result set to retrieve.
        Returns:
        a list of rows, which are each a map from output column (in alternate long and short form) to value.

      • getRowsAsMaps

        public java.util.List<java.util.Map<java.lang.String,​java.lang.Object>> getRowsAsMaps​(java.lang.String query)
        Get results for a query as rows of objects. Get up to the maximum result size of 10,000,000 rows from the beginning.
        Parameters:
        query - The query to run.
        Returns:
        a list of rows, which are each a map from output column (in alternate long and short form) to value.

      • getRowListIterator

        public java.util.Iterator<java.util.List<java.lang.Object>> getRowListIterator​(java.lang.String query,
                                                                               Page page)
        Get an iterator over the results of a query. The iterator returns a representation of one row at a time, in the order received over the connection.
        Parameters:
        query - the query to run.
        page - The subsection of the result set to retrieve.
        Returns:
        an iterator over the rows, where each row is a list of objects.

      • getRowListIterator

        public java.util.Iterator<java.util.List<java.lang.Object>> getRowListIterator​(java.lang.String query)
        Get an iterator over the results of a query. The iterator returns a representation of one row at a time, in the order received over the connection. Retrieves up to the maximum result size of 10,000,000 rows from the beginning.
        Parameters:
        query - the query to run.
        Returns:
        an iterator over the rows, where each row is a list of objects.

      • getRowMapIterator

        public java.util.Iterator<java.util.Map<java.lang.String,​java.lang.Object>> getRowMapIterator​(java.lang.String query,
                                                                                                    Page page)
        Get an iterator over the results of a query. The iterator returns a representation of one row at a time, in the order received over the connection.
        Parameters:
        query - the query to run.
        page - The subsection of the result set to retrieve.
        Returns:
        an iterator over the rows, where each row is a mapping from output column to value.

      • getRowMapIterator

        public java.util.Iterator<java.util.Map<java.lang.String,​java.lang.Object>> getRowMapIterator​(java.lang.String query)
        Get an iterator over the results of a query. The iterator returns a representation of one row at a time, in the order received over the connection, up to the maximum result size of 10,000,000 rows from the beginning.
        Parameters:
        query - the query to run.
        Returns:
        an iterator over the rows, where each row is a mapping from output column to value.

      • getRows

        protected RowResultSet getRows​(org.intermine.pathquery.PathQuery query,
                               Page page)

      • getNumericSummary

        public QueryService.NumericSummary getNumericSummary​(org.intermine.pathquery.PathQuery query,
                                                     java.lang.String path)
        Get a summary for the values in column of a query. The column must represent a column of numeric values.
        Parameters:
        query - The query to summarise.
        path - The column to summarise.
        Returns:
        A summary.

      • getSummary

        public java.util.Map<java.lang.String,​java.lang.Integer> getSummary​(org.intermine.pathquery.PathQuery query,
                                                                          java.lang.String summaryPath)
        Get a summary for the values in column of a query. The column must represent a column of non-numeric values. The map returned represents each possible value as a key, with the count of the occurrences of that value as the associated value for that key. The map supports predictable iteration ordering from the most request value to the least.
        Parameters:
        query - The query to summarise.
        summaryPath - The column to summarise.
        Returns:
        A summary.

      • getSummary

        public java.util.Map<java.lang.String,​java.lang.Integer> getSummary​(org.intermine.pathquery.PathQuery query,
                                                                          java.lang.String path,
                                                                          Page page)
        Get a summary for the values in column of a query. The column must represent a column of non-numeric values. The map returned represents each possible value as a key, with the count of the occurrences of that value as the associated value for that key. The map supports predictable iteration ordering from the most request value to the least.
        Parameters:
        query - The query to summarise.
        path - The column to summarise.
        page - The subsection of the summary to retrieve.
        Returns:
        A summary.