Source file database_intf.ml

(* Shared signature of the database entry points; see [Databases.S]. *)

type 'a io = unit -> 'a

type batch_validation_error = Cosmos.Databases_core.batch_validation_error =
  | Too_many_operations of int
  | Mixed_patch_operations
  | Empty_batch

type cosmos_error = Cosmos.Databases_core.Cosmos_error.t

module Response_headers = Cosmos.Databases_core.Response_headers

module type S = sig
  val get_code : Cohttp.Response.t -> int

  val list_databases :
    ?timeout:float ->
    unit ->
    (int * Cosmos.Json_converter_t.list_databases, cosmos_error) result io

  val create :
    ?timeout:float ->
    string ->
    (int * Cosmos.Json_converter_t.database option, cosmos_error) result io

  val create_if_not_exists :
    ?timeout:float ->
    string ->
    (int * Cosmos.Json_converter_t.database option, cosmos_error) result io

  val get :
    ?timeout:float ->
    string ->
    (int * Cosmos.Json_converter_t.database option, cosmos_error) result io

  val delete : ?timeout:float -> string -> (int, cosmos_error) result io

  module Collection : sig
    val list :
      ?timeout:float ->
      string ->
      (int * Cosmos.Json_converter_t.list_collections, cosmos_error) result io

    val create :
      ?indexing_policy:Cosmos.Json_converter_t.indexing_policy option ->
      ?offer_throughput:int ->
      partition_key:Cosmos.Json_converter_t.create_partition_key ->
      ?timeout:float ->
      string ->
      string ->
      (int * Cosmos.Json_converter_t.collection option, cosmos_error) result io

    val create_if_not_exists :
      ?indexing_policy:Cosmos.Json_converter_t.indexing_policy option ->
      ?offer_throughput:int ->
      partition_key:Cosmos.Json_converter_t.create_partition_key ->
      ?timeout:float ->
      string ->
      string ->
      (int * Cosmos.Json_converter_t.collection option, cosmos_error) result io

    val get :
      ?timeout:float ->
      string ->
      string ->
      (int * Cosmos.Json_converter_t.collection option, cosmos_error) result io

    val delete :
      ?timeout:float -> string -> string -> (int, cosmos_error) result io

    module Document : sig
      type indexing_directive = Include | Exclude

      val create :
        ?is_upsert:bool ->
        ?indexing_directive:indexing_directive ->
        partition_key:string ->
        ?timeout:float ->
        string ->
        string ->
        string ->
        (int * Cosmos.Json_converter_t.collection option, cosmos_error) result
        io

      val create_multiple :
        ?is_upsert:bool ->
        ?indexing_directive:indexing_directive ->
        ?timeout:float ->
        ?chunk_size:int ->
        string ->
        string ->
        (string * string) list ->
        (int * Cosmos.Json_converter_t.collection option, cosmos_error) result
        list
        io

      type list_result_meta_data = {
        rid : string;
        self : string;
        etag : string;
        ts : int;
        attachments : string;
      }

      type list_result = {
        rid : string;
        documents : (string * list_result_meta_data option) list;
        count : int;
      }

      val list :
        ?max_item_count:int ->
        ?continuation:string ->
        ?consistency_level:string ->
        ?session_token:string ->
        ?a_im:bool ->
        ?if_none_match:string ->
        ?partition_key_range_id:string ->
        ?timeout:float ->
        string ->
        string ->
        (int * Response_headers.t * list_result, cosmos_error) result io
      (** [list] is the legacy document-feed operation. For change-feed
          consumers, use [Change_feed.read], whose [304] result is explicit. *)

      type consistency_level = Strong | Bounded | Session | Eventual

      val string_of_consistency_level : consistency_level -> string

      val get :
        ?if_none_match:string ->
        partition_key:string ->
        ?consistency_level:consistency_level ->
        ?session_token:string ->
        ?timeout:float ->
        string ->
        string ->
        string ->
        (int * string, cosmos_error) result io

      val replace :
        ?indexing_directive:indexing_directive ->
        partition_key:string ->
        ?if_match:string ->
        ?timeout:float ->
        string ->
        string ->
        string ->
        string ->
        (int * string, cosmos_error) result io

      val delete :
        partition_key:string ->
        ?timeout:float ->
        string ->
        string ->
        string ->
        (int, cosmos_error) result io

      val delete_multiple :
        partition_key:string ->
        ?timeout:float ->
        ?chunk_size:int ->
        string ->
        string ->
        string list ->
        (int, cosmos_error) result list io

      val query :
        ?max_item_count:int ->
        ?continuation:string ->
        ?consistency_level:string ->
        ?session_token:string ->
        ?is_partition:bool ->
        ?partition_key:string ->
        ?timeout:float ->
        string ->
        string ->
        Cosmos.Json_converter_t.query ->
        (int * Response_headers.t * list_result, cosmos_error) result io
    end

    module Partition_key_range : sig
      val list :
        ?max_item_count:int ->
        ?continuation:string ->
        ?timeout:float ->
        string ->
        string ->
        ( int
          * Response_headers.t
          * Cosmos.Json_converter_t.list_partition_key_ranges,
          cosmos_error )
        result
        io
      (** Partition-key ranges can be enumerated for caller-managed fan-out. *)

      val ids :
        ?timeout:float ->
        string ->
        string ->
        (int * string list, cosmos_error) result io
    end

    module Change_feed : sig
      (** Pull-model latest-version change feed operations. *)
      module Mode : sig
        type t = Latest_version

        val string_of : t -> string
      end

      module Start_from : sig
        type t =
          | Beginning
          | Now
          | Point_in_time of float
          | Continuation of string

        val string_of : t -> string
      end

      module Scope : sig
        type t =
          | Container
          | Partition_key of string
          | Partition_key_range of string

        val string_of : t -> string
      end

      type page = {
        rid : string;
        documents : (string * Document.list_result_meta_data option) list;
        count : int;
        continuation : string;
        has_more_pages : bool;
            (** Presence of [x-ms-continuation]; Azure may omit it for change
                feed. Continue with [Continuation continuation] until 304, as
                [drain] does. *)
        session_token : string option;
      }

      type drain_result = {
        pages : page list;
        checkpoint : string;
        caught_up : bool;
      }

      val read :
        ?mode:Mode.t ->
        ?start_from:Start_from.t ->
        ?scope:Scope.t ->
        ?max_item_count:int ->
        ?session_token:string ->
        ?timeout:float ->
        string ->
        string ->
        (int * Response_headers.t * page option, cosmos_error) result io
      (** [read db coll] reads one page. [Ok (304, _, None)] means the feed is
          idle, not that the request failed. Persist [page.continuation] and
          resume with [Start_from.Continuation]. A supplied timeout applies
          independently to each request attempt; exhausted 429 retries are
          reported as [Timeout_error]. *)

      val is_partition_split : cosmos_error -> bool

      val drain :
        ?mode:Mode.t ->
        ?start_from:Start_from.t ->
        ?scope:Scope.t ->
        ?max_item_count:int ->
        ?max_pages:int ->
        ?timeout:float ->
        string ->
        string ->
        (drain_result, cosmos_error) result io

      val fold :
        ?mode:Mode.t ->
        ?start_from:Start_from.t ->
        ?scope:Scope.t ->
        ?max_item_count:int ->
        ?poll_interval:float ->
        ?max_polls:int ->
        ?timeout:float ->
        string ->
        string ->
        init:'acc ->
        f:('acc -> page -> ('acc, string) result io) ->
        ('acc * string, cosmos_error) result io
    end

    module Batch : sig
      type operation =
        | Create of {
            if_match : string option;
            if_none_match : string option;
            body : string;
          }
        | Upsert of {
            if_match : string option;
            if_none_match : string option;
            body : string;
          }
        | Read of {
            id : string;
            if_match : string option;
            if_none_match : string option;
          }
        | Delete of {
            id : string;
            if_match : string option;
            if_none_match : string option;
          }
        | Replace of {
            id : string;
            if_match : string option;
            if_none_match : string option;
            body : string;
          }
        | Patch of {
            id : string;
            if_match : string option;
            patch_op : patch_operation;
          }

      and patch_operation =
        | Add of { path : string; value : string }
        | Set of { path : string; value : string }
        | ReplacePath of { path : string; value : string }
        | Remove of { path : string }
        | Increment of { path : string; value : int }

      type operation_result = {
        status_code : int;
        request_charge : float;
        etag : string option;
        resource_body : string option;
      }

      type batch_result = {
        outcomes : operation_result list;
        total_request_charge : float;
      }

      type validation_error = batch_validation_error =
        | Too_many_operations of int
        | Mixed_patch_operations
        | Empty_batch

      val validate : operation list -> (unit, validation_error) result

      val execute :
        ?timeout:float ->
        ?atomic:bool ->
        partition_key:string ->
        string ->
        string ->
        operation list ->
        (batch_result, cosmos_error) result io
    end

    module Batch_builder : sig
      type t

      val empty : t

      val add_create :
        ?if_match:string -> ?if_none_match:string -> body:string -> t -> t

      val add_upsert :
        ?if_match:string -> ?if_none_match:string -> body:string -> t -> t

      val add_read :
        ?if_match:string -> ?if_none_match:string -> id:string -> t -> t

      val add_delete :
        ?if_match:string -> ?if_none_match:string -> id:string -> t -> t

      val add_replace :
        ?if_match:string ->
        ?if_none_match:string ->
        id:string ->
        body:string ->
        t ->
        t

      val add_patch :
        ?if_match:string ->
        id:string ->
        patch_op:Batch.patch_operation ->
        t ->
        t

      val build : t -> (Batch.operation list, Batch.validation_error) result
      val to_operations : t -> Batch.operation list
      val length : t -> int
    end
  end

  module User : sig
    val create :
      ?timeout:float ->
      string ->
      string ->
      (int * Cosmos.Json_converter_t.user, cosmos_error) result io

    val list :
      ?timeout:float ->
      string ->
      (int * Cosmos.Json_converter_t.list_users, cosmos_error) result io

    val get :
      ?timeout:float ->
      string ->
      string ->
      (int * Cosmos.Json_converter_t.user, cosmos_error) result io

    val replace :
      ?timeout:float ->
      string ->
      string ->
      string ->
      (int * Cosmos.Json_converter_t.user, cosmos_error) result io

    val delete :
      ?timeout:float -> string -> string -> (int, cosmos_error) result io
  end

  module Permission : sig
    type permission_mode = Read | All

    val create :
      ?timeout:float ->
      ?expiry_seconds:int ->
      dbname:string ->
      user_name:string ->
      coll_name:string ->
      permission_mode ->
      permission_name:string ->
      (int * Cosmos.Json_converter_t.permission, cosmos_error) result io
    (** [expiry_seconds] sets [x-ms-documentdb-expiry-seconds], the validity of
        the returned resource token (1..18000, default 3600). *)

    val list :
      ?timeout:float ->
      dbname:string ->
      user_name:string ->
      unit ->
      (int * Cosmos.Json_converter_t.list_permissions, cosmos_error) result io

    val get :
      ?timeout:float ->
      ?expiry_seconds:int ->
      dbname:string ->
      user_name:string ->
      permission_name:string ->
      unit ->
      (int * Cosmos.Json_converter_t.permission, cosmos_error) result io

    val replace :
      ?timeout:float ->
      ?expiry_seconds:int ->
      dbname:string ->
      user_name:string ->
      coll_name:string ->
      permission_mode ->
      permission_name:string ->
      (int * Cosmos.Json_converter_t.permission, cosmos_error) result io

    val delete :
      ?timeout:float ->
      dbname:string ->
      user_name:string ->
      permission_name:string ->
      unit ->
      (int, cosmos_error) result io
  end

  module Offer : sig
    module Throughput : sig
      type t = Manual of int | Autoscale of { max_throughput : int }

      val to_content : t -> Cosmos.Json_converter_t.offer_content
      val of_content : Cosmos.Json_converter_t.offer_content -> t option
      val string_of : t -> string
    end

    val list :
      ?timeout:float ->
      unit ->
      (int * Cosmos.Json_converter_t.list_offers, cosmos_error) result io
    (** [list ()] returns all throughput offers in the account. Requires
        master-key authentication. *)

    val get :
      ?timeout:float ->
      string ->
      (int * Cosmos.Json_converter_t.offer, cosmos_error) result io
    (** [get offer_rid] returns the offer identified by [offer_rid]. Requires
        master-key authentication. *)

    val query :
      ?max_item_count:int ->
      ?continuation:string ->
      ?timeout:float ->
      Cosmos.Json_converter_t.query ->
      ( int * Response_headers.t * Cosmos.Json_converter_t.list_offers,
        cosmos_error )
      result
      io

    val replace :
      ?migrate:[ `To_autoscale | `To_manual ] ->
      ?timeout:float ->
      Cosmos.Json_converter_t.offer ->
      Throughput.t ->
      (int * Cosmos.Json_converter_t.offer, cosmos_error) result io

    val get_for_collection :
      ?timeout:float ->
      string ->
      string ->
      (int * Cosmos.Json_converter_t.offer option, cosmos_error) result io

    val get_for_database :
      ?timeout:float ->
      string ->
      (int * Cosmos.Json_converter_t.offer option, cosmos_error) result io

    val get_throughput :
      ?timeout:float ->
      string ->
      string ->
      (int * Throughput.t option, cosmos_error) result io
    (** [get_throughput dbname coll_name] returns the collection's provisioned
        throughput, or [None] for serverless accounts. Requires master-key
        authentication. *)

    val set_throughput :
      ?migrate:[ `To_autoscale | `To_manual ] ->
      ?timeout:float ->
      string ->
      string ->
      Throughput.t ->
      (int * Cosmos.Json_converter_t.offer, cosmos_error) result io
    (** [set_throughput dbname coll_name throughput] changes the collection's
        provisioned throughput. Requires master-key authentication and is
        unavailable for serverless accounts. *)
  end
end