docs: def update_dataset(dataset_id, name, data_type, val, unit_id, metadata={}, flush=True, **kwargs):
      """
          Update an existing dataset
      """
  
      if dataset_id is None:
          raise HydraError("Dataset must have an ID to be updated.")
  
      user_id = kwargs.get('user_id')
  
      dataset = db.DBSession.query(Dataset).filter(Dataset.id==dataset_id).one()
      #This dataset been seen before, so it may be attached
      #to other scenarios, which may be locked. If they are locked, we must
      #not change their data, so new data must be created for the unlocked scenarios
      locked_scenarios = []
      unlocked_scenarios = []
      for dataset_rs in dataset.resourcescenarios:
          if dataset_rs.scenario.locked == 'Y':
              locked_scenarios.append(dataset_rs)
          else:
              unlocked_scenarios.append(dataset_rs)
  
      #Are any of these scenarios locked?
      if len(locked_scenarios) > 0:
          #If so, create a new dataset and assign to all unlocked datasets.
          dataset = add_dataset(data_type,
                                  val,
                                  unit_id,
                                  metadata=metadata,
                                  name=name,
                                  user_id=kwargs['user_id'])
          for unlocked_rs in unlocked_scenarios:
              unlocked_rs.dataset = dataset
  
      else:
  
          dataset.type  = data_type
          dataset.value = val
          dataset.set_metadata(metadata)
  
          dataset.unit_id = unit_id
          dataset.name  = name
          dataset.created_by = kwargs['user_id']
          dataset.hash  = dataset.set_hash()
  
          #Is there a dataset in the DB already which is identical to the updated dataset?
          existing_dataset = db.DBSession.query(Dataset).filter(Dataset.hash==dataset.hash, Dataset.id != dataset.id).first()
          if existing_dataset is not None and existing_dataset.check_user(user_id):
              log.warning("An identical dataset %s has been found to dataset %s."
                       " Deleting dataset and returning dataset %s",
                       existing_dataset.id, dataset.id, existing_dataset.id)
              db.DBSession.delete(dataset)
              dataset = existing_dataset
      if flush==True:
          db.DBSession.flush()
  
      return dataset