class_docstr: An annotation database instance.
  
  This class facilitates the annotation of genetic datasets with variant
  annotations. It accepts either an HTTP(S) URL to an Annotation DB
  configuration or a Python :obj:`dict` describing an Annotation DB
  configuration. User must specify the `region` (``'us'`` or ``'eu'``) in which
  the cluster is running if connecting to the default Hail Annotation DB.
  User must also specify the `cloud` platform that they are using (``'gcp'``
  or ``'aws'``).
  
  Parameters
  ----------
  region : :obj:`str`
      Region cluster is running in, either ``'us'`` or ``'eu'``
      (default is ``'us'``).
  cloud : :obj:`str`
      Cloud platform, either ``'gcp'`` or ``'aws'`` (default is ``'gcp'``).
  url : :obj:`str`, optional
      Optional URL to annotation DB configuration, if using custom configuration
      (default is ``None``).
  config : :obj:`str`, optional
      Optional :obj:`dict` describing an annotation DB configuration, if using
      custom configuration (default is ``None``).
  
  Note
  ----
  The ``'aws'`` `cloud` platform is currently only available for the ``'us'``
  `region`. If `region` is ``'eu'``, `cloud` must be set to ``'gcp'``.
  
  Examples
  --------
  Create an annotation database connecting to the default Hail Annotation DB:
  
  >>> db = hl.experimental.DB(region='us', cloud='gcp')
docstr: Add annotations from datasets specified by name to a relational
  object.
  
  List datasets with :attr:`~.available_datasets`.
  
  An interactive query builder is available in the
  `Hail Annotation Database documentation
  </docs/0.2/annotation_database_ui.html>`_.
  
  Examples
  --------
  Annotate a :class:`.MatrixTable` with ``gnomad_lof_metrics``:
  
  >>> db = hl.experimental.DB(region='us', cloud='gcp')
  >>> mt = db.annotate_rows_db(mt, 'gnomad_lof_metrics') # doctest: +SKIP
  
  Annotate a :class:`.Table` with ``clinvar_gene_summary``, ``CADD``,
  and ``DANN``:
  
  >>> db = hl.experimental.DB(region='us', cloud='gcp')
  >>> ht = db.annotate_rows_db(ht, 'clinvar_gene_summary', 'CADD', 'DANN') # doctest: +SKIP
  
  Notes
  -----
  
  If a dataset is gene-keyed, the annotation will be a dictionary mapping
  from gene name to the annotation value. There will be one entry for each
  gene overlapping the given locus.
  
  If a dataset does not have unique rows for each key (consider the
  ``gencode`` genes, which may overlap; and ``clinvar_variant_summary``,
  which contains many overlapping multiple nucleotide variants), then the
  result will be an array of annotation values, one for each row.
  
  Parameters
  ----------
  rel : :class:`.MatrixTable` or :class:`.Table`
      The relational object to which to add annotations.
  names : varargs of :class:`str`
      The names of the datasets with which to annotate `rel`.
  
  Returns
  -------
  :class:`.MatrixTable` or :class:`.Table`
      The relational object `rel`, with the annotations from `names`
      added.
docstr_tok: ["Add","annotations","from","datasets","specified","by","name","to","a","relational","object",".","List","datasets","with",":","attr",":","`","~.available_datasets","`",".","An","interactive","query","builder","is","available","in","the","`","Hail","Annotation","Database","documentation","<","\/docs\/0.2\/annotation_database_ui.html",">","`","_",".","Examples","--","--","--","--","Annotate","a",":","class",":","`",".MatrixTable","`","with","``","gnomad_lof_metrics","``",":",">",">",">","db","=","hl.experimental.DB","(","region='us","'",",","cloud='gcp","'",")",">",">",">","mt","=","db.annotate_rows_db","(","mt",",","'gnomad_lof_metrics","'",")","#","doctest",":","+SKIP","Annotate","a",":","class",":","`",".Table","`","with","``","clinvar_gene_summary","``",",","``","CADD","``",",","and","``","DANN","``",":",">",">",">","db","=","hl.experimental.DB","(","region='us","'",",","cloud='gcp","'",")",">",">",">","ht","=","db.annotate_rows_db","(","ht",",","'clinvar_gene_summary","'",",","'CADD","'",",","'DANN","'",")","#","doctest",":","+SKIP","Notes","--","--","-","If","a","dataset","is","gene-keyed",",","the","annotation","will","be","a","dictionary","mapping","from","gene","name","to","the","annotation","value",".","There","will","be","one","entry","for","each","gene","overlapping","the","given","locus",".","If","a","dataset","does","not","have","unique","rows","for","each","key","(","consider","the","``","gencode","``","genes",",","which","may","overlap",";","and","``","clinvar_variant_summary","``",",","which","contains","many","overlapping","multiple","nucleotide","variants",")",",","then","the","result","will","be","an","array","of","annotation","values",",","one","for","each","row",".","Parameters","--","--","--","--","--","rel",":",":","class",":","`",".MatrixTable","`","or",":","class",":","`",".Table","`","The","relational","object","to","which","to","add","annotations",".","names",":","varargs","of",":","class",":","`","str","`","The","names","of","the","datasets","with","which","to","annotate","`","rel","`",".","Returns","--","--","--","-",":","class",":","`",".MatrixTable","`","or",":","class",":","`",".Table","`","The","relational","object","`","rel","`",",","with","the","annotations","from","`","names","`","added","."]
code: def annotate_rows_db(
      self, rel: Union[Table, MatrixTable], *names: str
  ) -> Union[Table, MatrixTable]:
      """Add annotations from datasets specified by name to a relational
      object.
  
      List datasets with :attr:`~.available_datasets`.
  
      An interactive query builder is available in the
      `Hail Annotation Database documentation
      </docs/0.2/annotation_database_ui.html>`_.
  
      Examples
      --------
      Annotate a :class:`.MatrixTable` with ``gnomad_lof_metrics``:
  
      >>> db = hl.experimental.DB(region='us', cloud='gcp')
      >>> mt = db.annotate_rows_db(mt, 'gnomad_lof_metrics') # doctest: +SKIP
  
      Annotate a :class:`.Table` with ``clinvar_gene_summary``, ``CADD``,
      and ``DANN``:
  
      >>> db = hl.experimental.DB(region='us', cloud='gcp')
      >>> ht = db.annotate_rows_db(ht, 'clinvar_gene_summary', 'CADD', 'DANN') # doctest: +SKIP
  
      Notes
      -----
  
      If a dataset is gene-keyed, the annotation will be a dictionary mapping
      from gene name to the annotation value. There will be one entry for each
      gene overlapping the given locus.
  
      If a dataset does not have unique rows for each key (consider the
      ``gencode`` genes, which may overlap; and ``clinvar_variant_summary``,
      which contains many overlapping multiple nucleotide variants), then the
      result will be an array of annotation values, one for each row.
  
      Parameters
      ----------
      rel : :class:`.MatrixTable` or :class:`.Table`
          The relational object to which to add annotations.
      names : varargs of :class:`str`
          The names of the datasets with which to annotate `rel`.
  
      Returns
      -------
      :class:`.MatrixTable` or :class:`.Table`
          The relational object `rel`, with the annotations from `names`
          added.
      """
      rel = self._row_lens(rel)
      if len(set(names)) != len(names):
          raise ValueError(
              f"cannot annotate same dataset twice,"
              f" please remove duplicates from: {names}"
          )
      self._check_availability(names)
      datasets = [self._dataset_by_name(name) for name in names]
      if any(dataset.is_gene_keyed for dataset in datasets):
          gene_field, rel = self._annotate_gene_name(rel)
      else:
          gene_field = None
      for dataset in datasets:
          if dataset.is_gene_keyed:
              genes = rel.select(gene_field).explode(gene_field)
              genes = genes.annotate(
                  **{
                      dataset.name: dataset.index_compatible_version(
                          genes[gene_field]
                      )
                  }
              )
              genes = genes.group_by(*genes.key).aggregate(
                  **{
                      dataset.name: hl.dict(
                          hl.agg.filter(
                              hl.is_defined(genes[dataset.name]),
                              hl.agg.collect(
                                  (
                                      genes[gene_field],
                                      genes[dataset.name],
                                  )
                              ),
                          )
                      )
                  }
              )
              rel = rel.annotate(
                  **{dataset.name: genes.index(rel.key)[dataset.name]}
              )
          else:
              indexed_value = dataset.index_compatible_version(rel.key)
              if (
                  isinstance(indexed_value.dtype, hl.tstruct)
                  and len(indexed_value.dtype) == 0
              ):
                  indexed_value = hl.is_defined(indexed_value)
              rel = rel.annotate(**{dataset.name: indexed_value})
      if gene_field:
          rel = rel.drop(gene_field)
      return rel.unlens()
  
imports: import json
  import os
  import warnings
  from typing import Iterable, List, Optional, Set, Tuple, Union
  import hail
  import pkg_resources
  from hailtop.utils import external_requests_client_session, retry_response_returning_functions
  from .lens import MatrixRows, TableRows
  from ..expr import StructExpression
  from ..matrixtable import MatrixTable, matrix_table_type
  from ..table import Table, table_type
  from ..typecheck import oneof, typecheck_method
  from ..utils.java import Env, info
label_desc: Use image node_id 7 for calling the DB obj's underlying member method code with example usage: obj.annotate_rows_db(rel) and returns: rel