Geo query includes geo-distance query, geo-bounding box query, and geo-polygon query.

Prerequisites

  • An OTSClient instance is initialized. For more information, see Initialization.
  • A data table is created. Data is written to the table.
  • A search index is created for the data table. For more information, see Create search indexes.

Geo-distance query

You can use geo-distance query to specify a circular geographical area consisting of a central point and a radius as a filtering condition in a query. Tablestore returns the rows in which the value of the Geopoint column falls within the circular geographical area.

  • Parameters
    ParameterDescription
    FieldNameThe name of the column. The type of the column values is Geopoint.
    CenterPointThe coordinate pair of the central point. The coordinate pair consists of latitude and longitude values.

    This parameter value must be in the format of "latitude,longitude". Valid values of latitude: [-90,90]. Valid values of longitude: [-180,180]. Example: “35.8,-45.91".

    DistanceInMeterThe radius of the circular geographical area. The value of this parameter is of the DOUBLE data type. Unit: meter.
    QueryThe query statement for the search index. Set the query type to GeoDistanceQuery.
    TableNameThe name of the table.
    IndexNameThe name of the search index.
    ColumnsToGetSpecifies whether to return all columns of each row that meets the query conditions. You can configure ReturnAll, Columns, and ReturnAllFromIndex for this parameter.
    The default value of ReturnAll is false, which indicates that not all columns are returned. You can use one of the following methods to specify the columns that you want to return. If you do not use the following methods to specify the columns that you want to return, only the primary key columns are returned.
    • Configure Columns to specify the columns that you want to return.
    • Set ReturnAllFromIndex to true to return all columns from the search index.

    If you set ReturnAll to true, all columns are returned.

  • Examples
    /// <summary> 
    /// Search the table for rows in which the value of the geo_type_col column falls within a circular geographical area. 
    /// </summary>
    /// <param name="client"></param>
    public static void GeoDistanceQuery(OTSClient client)
    {
        SearchQuery searchQuery = new SearchQuery();
        GeoDistanceQuery geoDistanceQuery = new GeoDistanceQuery(); // Set the query type to GeoDistanceQuery. 
        geoDistanceQuery.FieldName = Geo_type_col;
        geoDistanceQuery.CenterPoint = "10,11"; // Specify the coordinate pair for a central point. 
        geoDistanceQuery.DistanceInMeter = 10000; // Set the radius of the circular geographical area to 10,000. Unit: meter. 
        searchQuery.Query = geoDistanceQuery;
    
        SearchRequest searchRequest = new SearchRequest(TableName, IndexName, searchQuery);
    
        ColumnsToGet columnsToGet = new ColumnsToGet();
        columnsToGet.Columns = new List<string>() { Geo_type_col }; // Specify that the Col_GeoPoint column is returned. 
        searchRequest.ColumnsToGet = columnsToGet;
    
        SearchResponse response = client.Search(searchRequest);
        Console.WriteLine(response.TotalCount);
    }
                

Geo-bounding box query

You can use geo-bounding box query to specify a rectangular geographical area as a filtering condition in a query. Tablestore returns the rows in which the value of the Geopoint column falls within the rectangular geographical area.

  • Parameters
    ParameterDescription
    FieldNameThe name of the column. The type of the column values is Geopoint.
    TopLeftThe coordinate pair of the upper-left corner of the rectangular geographical area.
    BottomRightThe coordinate pair of the lower-right corner of the rectangular geographical area. The coordinate pairs of the upper-left corner and lower-right corner define a unique rectangular geographical area.

    This parameter value must be in the format of "latitude,longitude". Valid values of the latitude: [-90,90]. Valid values of longitude: [-180,180]. Example: “35.8,-45.91".

    QueryThe query statement for the search index. Set the query type to GeoBoundingBoxQuery.
    TableNameThe name of the table.
    IndexNameThe name of the search index.
    ColumnsToGetSpecifies whether to return all columns of each row that meets the query conditions. You can configure ReturnAll, Columns, and ReturnAllFromIndex for this parameter.
    The default value of ReturnAll is false, which indicates that not all columns are returned. You can use one of the following methods to specify the columns that you want to return. If you do not use the following methods to specify the columns that you want to return, only the primary key columns are returned.
    • Configure Columns to specify the columns that you want to return.
    • Set ReturnAllFromIndex to true to return all columns from the search index.

    If you set ReturnAll to true, all columns are returned.

  • Examples
    /// <summary>
    /// Search the table for rows in which the value of the geo_type_col column falls within the rectangular geographical area that is specified by an upper-left corner (coordinate pair: 10,0) and a lower-right corner (coordinate pair: 0,10). The data type of the geo_type_col column is Geopoint. 
    /// </summary>
    /// <param name="client"></param>
    public static void GeoBoundingBoxQuery(OTSClient client)
    {
        SearchQuery searchQuery = new SearchQuery();
        GeoBoundingBoxQuery geoBoundingBoxQuery = new GeoBoundingBoxQuery(); // Set the query type to GeoBoundingBoxQuery. 
        geoBoundingBoxQuery.FieldName = Geo_type_col; // Specify the column name. 
        geoBoundingBoxQuery.TopLeft = "10,0"; // Specify the coordinate pair for the upper-left corner of the rectangular geographical area. 
        geoBoundingBoxQuery.BottomRight = "0,10"; // Specify coordinate pair for the lower-right corner of the rectangular geographical area. 
        searchQuery.Query = geoBoundingBoxQuery;
    
        SearchRequest searchRequest = new SearchRequest(TableName, IndexName, searchQuery);
    
        var columnsToGet = new ColumnsToGet();
        columnsToGet.Columns = new List<string> { Geo_type_col }; // Specify that the Col_GeoPoint column is returned. 
        searchRequest.ColumnsToGet = columnsToGet;
    
        SearchResponse response = client.Search(searchRequest);
        Console.WriteLine(response.TotalCount);
    }

Geo-polygon query

You can use geo-polygon query to specify a polygon geographical area. Tablestore returns the rows in which the value of the Geopoint column falls within the polygon geographical area.

  • Parameters
    ParameterDescription
    FieldNameThe name of the column. The type of the column values is Geopoint.
    PointsThe coordinate pairs of the points that define a polygon geographical area.

    The coordinate pair of each point must be in the format of "latitude,longitude". Valid values of latitude: [-90,90]. Valid values of longitude: [-180,180]. Example: “35.8,-45.91".

    QueryThe query statement for the search index. Set the query type to GeoPolygonQuery.
    TableNameThe name of the table.
    IndexNameThe name of the search index.
    ColumnsToGetSpecifies whether to return all columns of each row that meets the query conditions. You can configure ReturnAll, Columns, and ReturnAllFromIndex for this parameter.
    The default value of ReturnAll is false, which indicates that not all columns are returned. You can use one of the following methods to specify the columns that you want to return. If you do not use the following methods to specify the columns that you want to return, only the primary key columns are returned.
    • Configure Columns to specify the columns that you want to return.
    • Set ReturnAllFromIndex to true to return all columns from the search index.

    If you set ReturnAll to true, all columns are returned.

  • Examples
    /// <summary>
    /// Search the table for rows in which the value of the geo_type_col column falls within a polygon geographical area. 
    /// </summary>
    /// <param name="client"></param>
    public static void GeoPolygonQuery(OTSClient client)
    {
        SearchQuery searchQuery = new SearchQuery();
        GeoPolygonQuery geoPolygonQuery = new GeoPolygonQuery(); // Set the query type to GeoPolygonQuery. 
        geoPolygonQuery.FieldName = Geo_type_col;
        geoPolygonQuery.Points = new List<string>() { "0,0", "10,0", "10,10" }; // Specify coordinate pairs for vertices of a polygon geographical area. 
        searchQuery.Query = geoPolygonQuery;
    
        SearchRequest searchRequest = new SearchRequest(TableName, IndexName, searchQuery);
    
        ColumnsToGet columnsToGet = new ColumnsToGet();
        columnsToGet.Columns = new List<string>() { Geo_type_col }; // Specify that the Col_GeoPoint column is returned. 
        searchRequest.ColumnsToGet = columnsToGet;
    
        SearchResponse response = client.Search(searchRequest);
        Console.WriteLine(response.TotalCount);
    }