edges_builder.h

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
 
#pragma once
 
#include <algorithm>
#include <any>
#include <memory>
#include <string>
#include <unordered_map>
#include <utility>
#include <vector>
 
#include "graphar/arrow/chunk_writer.h"
#include "graphar/fwd.h"
#include "graphar/graph_info.h"
#include "graphar/types.h"
 
namespace arrow {
class Array;
}
 
namespace graphar::builder {
 
class Edge {
 public:
  explicit Edge(IdType src_id, IdType dst_id)
      : src_id_(src_id), dst_id_(dst_id), empty_(true) {}
 
  inline bool Empty() const noexcept { return empty_; }
 
  inline IdType GetSource() const noexcept { return src_id_; }
 
  inline IdType GetDestination() const noexcept { return dst_id_; }
 
  // TODO(@acezen): Enable the property to be a vector(list).
  inline void AddProperty(const std::string& name, const std::any& val) {
    empty_ = false;
    properties_[name] = val;
  }
 
  inline const std::any& GetProperty(const std::string& property) const {
    return properties_.at(property);
  }
 
  inline const std::unordered_map<std::string, std::any>& GetProperties()
      const {
    return properties_;
  }
 
  inline bool ContainProperty(const std::string& property) const {
    return (properties_.find(property) != properties_.end());
  }
 
 private:
  IdType src_id_, dst_id_;
  bool empty_;
  std::unordered_map<std::string, std::any> properties_;
};
 
inline bool cmp_src(const Edge& a, const Edge& b) {
  return a.GetSource() < b.GetSource();
}
 
inline bool cmp_dst(const Edge& a, const Edge& b) {
  return a.GetDestination() < b.GetDestination();
}
 
class EdgesBuilder {
 public:
  explicit EdgesBuilder(
      const std::shared_ptr<EdgeInfo>& edge_info, const std::string& prefix,
      AdjListType adj_list_type, IdType num_vertices,
      std::shared_ptr<WriterOptions> writerOptions = nullptr,
      const ValidateLevel& validate_level = ValidateLevel::no_validate)
      : edge_info_(std::move(edge_info)),
        prefix_(prefix),
        adj_list_type_(adj_list_type),
        num_vertices_(num_vertices),
        writer_options_(writerOptions),
        validate_level_(validate_level) {
    if (validate_level_ == ValidateLevel::default_validate) {
      throw std::runtime_error(
          "default_validate is not allowed to be set as the global validate "
          "level for EdgesBuilder");
    }
    edges_.clear();
    num_edges_ = 0;
    is_saved_ = false;
    switch (adj_list_type) {
    case AdjListType::unordered_by_source:
      vertex_chunk_size_ = edge_info_->GetSrcChunkSize();
      break;
    case AdjListType::ordered_by_source:
      vertex_chunk_size_ = edge_info_->GetSrcChunkSize();
      break;
    case AdjListType::unordered_by_dest:
      vertex_chunk_size_ = edge_info_->GetDstChunkSize();
      break;
    case AdjListType::ordered_by_dest:
      vertex_chunk_size_ = edge_info_->GetDstChunkSize();
      break;
    default:
      vertex_chunk_size_ = edge_info_->GetSrcChunkSize();
    }
  }
 
  inline void SetValidateLevel(const ValidateLevel& validate_level) {
    if (validate_level == ValidateLevel::default_validate) {
      return;
    }
    validate_level_ = validate_level;
  }
 
  inline void SetWriterOptions(std::shared_ptr<WriterOptions> writer_options) {
    this->writer_options_ = writer_options;
  }
  inline std::shared_ptr<WriterOptions> GetWriterOptions() {
    return this->writer_options_;
  }
 
  inline ValidateLevel GetValidateLevel() const { return validate_level_; }
 
  inline void Clear() {
    edges_.clear();
    num_edges_ = 0;
    is_saved_ = false;
  }
 
  Status AddEdge(const Edge& e, const ValidateLevel& validate_level =
                                    ValidateLevel::default_validate) {
    // validate
    GAR_RETURN_NOT_OK(validate(e, validate_level));
    // add an edge
    IdType vertex_chunk_index = getVertexChunkIndex(e);
    edges_[vertex_chunk_index].push_back(e);
    num_edges_++;
    return Status::OK();
  }
 
  IdType GetNum() const { return num_edges_; }
 
  Status Dump();
 
  static Result<std::shared_ptr<EdgesBuilder>> Make(
      const std::shared_ptr<EdgeInfo>& edge_info, const std::string& prefix,
      AdjListType adj_list_type, IdType num_vertices,
      std::shared_ptr<WriterOptions> writer_options,
      const ValidateLevel& validate_level = ValidateLevel::no_validate) {
    if (!edge_info->HasAdjacentListType(adj_list_type)) {
      return Status::KeyError(
          "The adjacent list type ", AdjListTypeToString(adj_list_type),
          " doesn't exist in edge ", edge_info->GetEdgeType(), ".");
    }
    return std::make_shared<EdgesBuilder>(edge_info, prefix, adj_list_type,
                                          num_vertices, writer_options,
                                          validate_level);
  }
 
  static Result<std::shared_ptr<EdgesBuilder>> Make(
      const std::shared_ptr<EdgeInfo>& edge_info, const std::string& prefix,
      AdjListType adj_list_type, IdType num_vertices,
      const ValidateLevel& validate_level = ValidateLevel::no_validate) {
    if (!edge_info->HasAdjacentListType(adj_list_type)) {
      return Status::KeyError(
          "The adjacent list type ", AdjListTypeToString(adj_list_type),
          " doesn't exist in edge ", edge_info->GetEdgeType(), ".");
    }
    return std::make_shared<EdgesBuilder>(edge_info, prefix, adj_list_type,
                                          num_vertices, nullptr,
                                          validate_level);
  }
 
  static Result<std::shared_ptr<EdgesBuilder>> Make(
      const std::shared_ptr<GraphInfo>& graph_info, const std::string& src_type,
      const std::string& edge_type, const std::string& dst_type,
      const AdjListType& adj_list_type, IdType num_vertices,
      std::shared_ptr<WriterOptions> writer_options,
      const ValidateLevel& validate_level = ValidateLevel::no_validate) {
    auto edge_info = graph_info->GetEdgeInfo(src_type, edge_type, dst_type);
    if (!edge_info) {
      return Status::KeyError("The edge ", src_type, " ", edge_type, " ",
                              dst_type, " doesn't exist.");
    }
    return Make(edge_info, graph_info->GetPrefix(), adj_list_type, num_vertices,
                writer_options, validate_level);
  }
 
  static Result<std::shared_ptr<EdgesBuilder>> Make(
      const std::shared_ptr<GraphInfo>& graph_info, const std::string& src_type,
      const std::string& edge_type, const std::string& dst_type,
      const AdjListType& adj_list_type, IdType num_vertices,
      const ValidateLevel& validate_level = ValidateLevel::no_validate) {
    auto edge_info = graph_info->GetEdgeInfo(src_type, edge_type, dst_type);
    if (!edge_info) {
      return Status::KeyError("The edge ", src_type, " ", edge_type, " ",
                              dst_type, " doesn't exist.");
    }
    return Make(edge_info, graph_info->GetPrefix(), adj_list_type, num_vertices,
                nullptr, validate_level);
  }
 
 private:
  IdType getVertexChunkIndex(const Edge& e) {
    switch (adj_list_type_) {
    case AdjListType::unordered_by_source:
      return e.GetSource() / vertex_chunk_size_;
    case AdjListType::ordered_by_source:
      return e.GetSource() / vertex_chunk_size_;
    case AdjListType::unordered_by_dest:
      return e.GetDestination() / vertex_chunk_size_;
    case AdjListType::ordered_by_dest:
      return e.GetDestination() / vertex_chunk_size_;
    default:
      return e.GetSource() / vertex_chunk_size_;
    }
  }
 
  Status validate(const Edge& e, ValidateLevel validate_level) const;
 
  Status appendToArray(const std::shared_ptr<DataType>& type,
                       const std::string& property_name,
                       std::shared_ptr<arrow::Array>& array,  // NOLINT
                       const std::vector<Edge>& edges);
 
  template <Type type>
  Status tryToAppend(const std::string& property_name,
                     std::shared_ptr<arrow::Array>& array,  // NOLINT
                     const std::vector<Edge>& edges);
 
  Status tryToAppend(int src_or_dest,
                     std::shared_ptr<arrow::Array>& array,  // NOLINT
                     const std::vector<Edge>& edges);
 
  Result<std::shared_ptr<arrow::Table>> convertToTable(
      const std::vector<Edge>& edges);
 
  Result<std::shared_ptr<arrow::Table>> getOffsetTable(
      IdType vertex_chunk_index, const std::vector<Edge>& edges);
 
 private:
  std::shared_ptr<EdgeInfo> edge_info_;
  std::string prefix_;
  AdjListType adj_list_type_;
  std::unordered_map<IdType, std::vector<Edge>> edges_;
  IdType vertex_chunk_size_;
  IdType num_vertices_;
  IdType num_edges_;
  bool is_saved_;
  std::shared_ptr<WriterOptions> writer_options_;
  ValidateLevel validate_level_;
};
 
}  // namespace graphar::builder