feat: Implement parent/child BingTile functions (facebookincubator#12708)

Summary:
Pull Request resolved: facebookincubator#12708

These functions allow users to find the parent or children tiles of a BingTile.

Reviewed By: bikramSingh91

Differential Revision: D71413543

fbshipit-source-id: bcfa7f5a175362d22ff3542d1b3e0b922eb1ff18

Author: jagill

velox/docs/functions/presto/geospatial.rst

@@ -32,8 +32,31 @@ for more details.
 
 .. function:: bing_tile_coordinates(tile: BingTile) -> coords: row(integer,integer)
 
-   Returns the `x`, `y` coordinates of a given Bing tile as `row(x, y)`.
+    Returns the `x`, `y` coordinates of a given Bing tile as `row(x, y)`.
 
 .. function:: bing_tile_zoom_level(tile: BingTile) -> zoom_level: tinyint
 
-   Returns the zoom level of a given Bing tile.
+    Returns the zoom level of a given Bing tile.
+
+.. function:: bing_tile_parent(tile) -> parent: BingTile
+
+    Returns the parent of the Bing tile at one lower zoom level. Throws an
+    exception if tile is at zoom level 0.
+
+.. function:: bing_tile_parent(tile, parentZoom) -> parent: BingTile
+
+    Returns the parent of the Bing tile at the specified lower zoom level.
+    Throws an exception if parentZoom is less than 0, or parentZoom is greater
+    than the tile’s zoom.
+
+.. function:: bing_tile_children(tile) -> children: array(BingTile)
+
+    Returns the children of the Bing tile at one higher zoom level. Throws an
+    exception if tile is at max zoom level.
+
+.. function:: bing_tile_children(tile, childZoom) -> children: array(BingTile)
+
+    Returns the children of the Bing tile at the specified higher zoom level.
+    Throws an exception if childZoom is greater than the max zoom level, or
+    childZoom is less than the tile’s zoom.  The order is deterministic but not
+    specified.

velox/expression/fuzzer/ExpressionFuzzerTest.cpp

@@ -118,7 +118,9 @@ int main(int argc, char** argv) {
       // BingTiles throw VeloxUserError when zoom/x/y are out of range.
       "bing_tile",
       "bing_tile_zoom_level",
-      "bing_tile_coordinates"};
+      "bing_tile_coordinates",
+      "bing_tile_parent",
+      "bing_tile_children"};
   size_t initialSeed = FLAGS_seed == 0 ? std::time(nullptr) : FLAGS_seed;
 
   std::unordered_map<std::string, std::shared_ptr<ArgTypesGenerator>>

velox/functions/prestosql/GeospatialFunctions.h

@@ -91,4 +91,84 @@ struct BingTileCoordinatesFunction {
   }
 };
 
+template <typename T>
+struct BingTileParentFunction {
+  VELOX_DEFINE_FUNCTION_TYPES(T);
+
+  FOLLY_ALWAYS_INLINE Status
+  call(out_type<BingTile>& result, const arg_type<BingTile>& tile) {
+    uint64_t tileInt = tile;
+    uint8_t tileZoom = BingTileType::bingTileZoom(tile);
+    if (FOLLY_UNLIKELY(tileZoom == 0)) {
+      return Status::UserError(
+          fmt::format("Cannot call bing_tile_parent on zoom 0 tile"));
+    }
+    auto parent = BingTileType::bingTileParent(tileInt, tileZoom - 1);
+    if (FOLLY_UNLIKELY(parent.hasError())) {
+      return Status::UserError(parent.error());
+    }
+    result = parent.value();
+    return Status::OK();
+  }
+
+  FOLLY_ALWAYS_INLINE Status call(
+      out_type<BingTile>& result,
+      const arg_type<BingTile>& tile,
+      const arg_type<int8_t>& parentZoom) {
+    uint64_t tileInt = tile;
+    if (FOLLY_UNLIKELY(parentZoom < 0)) {
+      return Status::UserError(
+          fmt::format("Cannot call bing_tile_parent with negative zoom"));
+    }
+    auto parent = BingTileType::bingTileParent(tileInt, parentZoom);
+    if (FOLLY_UNLIKELY(parent.hasError())) {
+      return Status::UserError(parent.error());
+    }
+    result = parent.value();
+    return Status::OK();
+  }
+};
+
+template <typename T>
+struct BingTileChildrenFunction {
+  VELOX_DEFINE_FUNCTION_TYPES(T);
+
+  FOLLY_ALWAYS_INLINE Status
+  call(out_type<Array<BingTile>>& result, const arg_type<BingTile>& tile) {
+    uint64_t tileInt = tile;
+    uint8_t tileZoom = BingTileType::bingTileZoom(tile);
+    if (FOLLY_UNLIKELY(tileZoom >= BingTileType::kBingTileMaxZoomLevel)) {
+      return Status::UserError(
+          fmt::format("Cannot call bing_tile_children on zoom 23 tile"));
+    }
+    auto childrenRes = BingTileType::bingTileChildren(tileInt, tileZoom + 1);
+    if (FOLLY_UNLIKELY(childrenRes.hasError())) {
+      return Status::UserError(childrenRes.error());
+    }
+    std::vector<uint64_t> children = childrenRes.value();
+    result.reserve(children.size());
+    result.add_items(children);
+    return Status::OK();
+  }
+
+  FOLLY_ALWAYS_INLINE Status call(
+      out_type<Array<BingTile>>& result,
+      const arg_type<BingTile>& tile,
+      const arg_type<int8_t>& childZoom) {
+    uint64_t tileInt = tile;
+    if (FOLLY_UNLIKELY(childZoom < 0)) {
+      return Status::UserError(
+          fmt::format("Cannot call bing_tile_children with negative zoom"));
+    }
+    auto childrenRes = BingTileType::bingTileChildren(tileInt, childZoom);
+    if (FOLLY_UNLIKELY(childrenRes.hasError())) {
+      return Status::UserError(childrenRes.error());
+    }
+    std::vector<uint64_t> children = childrenRes.value();
+    result.reserve(children.size());
+    result.add_items(children);
+    return Status::OK();
+  }
+};
+
 } // namespace facebook::velox::functions

velox/functions/prestosql/registration/GeospatialFunctionsRegistration.cpp

@@ -37,6 +37,16 @@ void registerBingTileFunctions(const std::string& prefix) {
       BingTileCoordinatesFunction,
       Row<int32_t, int32_t>,
       BingTile>({prefix + "bing_tile_coordinates"});
+
+  // Parent/child tiles
+  registerFunction<BingTileParentFunction, BingTile, BingTile>(
+      {prefix + "bing_tile_parent"});
+  registerFunction<BingTileParentFunction, BingTile, BingTile, int8_t>(
+      {prefix + "bing_tile_parent"});
+  registerFunction<BingTileChildrenFunction, Array<BingTile>, BingTile>(
+      {prefix + "bing_tile_children"});
+  registerFunction<BingTileChildrenFunction, Array<BingTile>, BingTile, int8_t>(
+      {prefix + "bing_tile_children"});
 }
 
 } // namespace