Ajuda do LibreOffice 25.2
O serviço Dataset é usado para representar dados tabulares produzidos por um banco de dados. Com este serviço é possível:
Navegar e acessar os dados em um conjunto de dados.
Atualizar, inserir e remover registros em um conjunto de dados.
Atualizar e inserir registros usando o serviço Dataset é mais lento do que usar instruções SQL. Ao atualizar ou inserir grandes quantidades de registros, é recomendado utilizar instruções SQL em vez de utilizar os métodos deste serviço.
Antes de usar o serviço Dataset a biblioteca ScriptForge precisa ser carregada ou importada:
O serviço Dataset é invocado usando o método CreateDataset, que pode ser chamado de uma instância do serviço Database ou de outra instância Dataset.
O exemplo a seguir cria um Dataset a partir da tabela "Clientes" armazenada em um arquivo de banco de dados.
    oDatabase = CreateScriptService("Database", "C:\MyDatabase.odb")
    oDataset = oDatabase.CreateDataset("Clientes")
    With oDataset
        Do While .MoveNext()
            oValues = .Values()
            ' ...
        Loop
        .CloseDataset()
    End With
  Após a criação do Dataset, o registro atual é posicionado antes do primeiro registro.
O exemplo abaixo cria uma instância do serviço Dataset filtrando o conjunto de dados original.
    oNewDataset = oDataset.CreateDataset(Filter := "[City]='New York'")
  
    database = CreateScriptService("Database", r"C:\MyDatabase.odb")
    dataset = database.CreateDataset("Clientes")
    while dataset.MoveNext():
        values = dataset.Values
        # ...
    dataset.CloseDataset()
  
    new_dataset = dataset.CreateDataset(filter = "[Cidade]='São Paulo'")
  | Nome | Somente leitura | Tipo | Descrição | 
|---|---|---|---|
| BOF | Não | Boolean | Retorna True se a posição atual do registro for anterior ao primeiro registro no conjunto de dados, caso contrário, retorna False. Defina esta propriedade como True para mover o cursor para o início do conjunto de dados. Definir esta propriedade como False é ignorado. | 
| DefaultValues | Sim | Serviço Dictionary | Returna um Dictionary com valores padrão usados em cada campo no dataset. Os campos ou colunas no dataset são as chaves no dicionário. Os tipos de campo do banco de dados são convertidos em seus tipos de dados correspondentes em Basic ou Python. Quando o tipo do campo é indefinido, o valor padrão é Null se o campo for anulável ou Empty caso contrário. | 
| EOF | Não | Boolean | Retorna True se a posição atual do registro for após o último registro no conjunto de dados, caso contrário, retorna False. Defina esta propriedade como True para mover o cursor para o final do conjunto de dados. Definir esta propriedade como False é ignorado. | 
| Fields | Sim | Array | Retorna um Array contendo os nomes de todos os campos do conjunto de dados. | 
| Filter | Sim | String | Retorna o filtro aplicado além das eventuais cláusulas WHERE na instrução SQL inicial. Esta propriedade é expressa como uma cláusula WHERE sem a palavra-chave "WHERE". | 
| OrderBy | Sim | String | Retorna a cláusula de ordenação que substitui a eventual cláusula ORDER BY presente na instrução SQL inicial. Esta propriedade é expressa como uma cláusula ORDER BY sem as palavras-chave "ORDER BY". | 
| ParentDatabase | Sim | Serviço Database | Retorna a instância Database correspondente ao banco de dados pai do conjunto de dados atual. | 
| RowCount | Sim | Long | Retorna o número exato de registros no conjunto de dados. Note que a avaliação desta propriedade implica navegar em todo o conjunto de dados, o que pode ser dispendioso dependendo do tamanho do conjunto de dados. | 
| RowNumber | Sim | Long | Retorna o número do registro atual começando em 1. Retorna 0 se esta propriedade for desconhecida. | 
| Source | Sim | String | Retorna a origem do conjunto de dados. Pode ser um nome de tabela, um nome de consulta ou uma instrução SQL. | 
| SourceType | Sim | String | Retorna a origem do conjunto de dados. Pode ser um dos seguintes valores expressos como uma string: TABLE, QUERY ou SQL. | 
| UpdatableFields | Sim | Array | Retorna um Array contendo os nomes dos campos do conjunto de dados que são atualizáveis. | 
| Values | Sim | Array | Retorna um Dictionary contendo os pares (nome do campo: valor) do registro atual no conjunto de dados. | 
| XRowSet | Sim | Objeto UNO | Retorna o objeto UNO com.sun.star.sdb.RowSet que representa o conjunto de dados. | 
| Lista de Métodos no Serviço Dataset | ||
|---|---|---|
Fecha o conjunto de dados atual. Este método retorna True quando bem-sucedido.
Recomenda-se fechar o conjunto de dados após seu uso para liberar recursos.
svc.CloseDataset(): bool
      oDataset = oDatabase.CreateDataset("MyTable")
      ' ...
      oDataset.CloseDataset()
    
      dataset = database.CreateDataset("MyTable")
      # ...
      dataset.CloseDataset()
    Retorna uma instância do serviço Dataset de um conjunto de dados existente, aplicando o filtro especificado e as instruções ORDER BY.
svc.CreateDataset(opt filter: str, opt orderby: str): svc
filter: especifica a condição que os registros devem atender para serem incluídos no conjunto de dados retornado. Este argumento é expresso como uma instrução SQL WHERE sem a palavra-chave "WHERE". Se este argumento não for especificado, então o filtro usado no conjunto de dados atual será aplicado, caso contrário, o filtro atual será substituído por este argumento.
orderby: especifica a ordem do conjunto de dados como uma instrução SQL ORDER BY sem a palavra-chave "ORDER BY". Se este argumento não for especificado, então a ordem de classificação usada no conjunto de dados atual será aplicada; caso contrário, a ordem de classificação atual será substituída por este argumento.
      ' Use uma string vazia para remover o filtro atual
      oNewDataset = oDataset.CreateDataset(Filter := "")
      ' Exemplos de filtros comuns
      oNewDataset = oDataset.CreateDataset(Filter := "[Name] = 'John'")
      oNewDataset = oDataset.CreateDataset(Filter := "[Name] LIKE 'A'")
      É possível acrescentar condições adicionais ao filtro atual
      oNewDataset = oDataset.CreateDataset(Filter := "(" & oDataset.Filter & ") AND [Name] LIKE 'A'")
    
      new_dataset = dataset.CreateDataset(filter = "")
      new_dataset = dataset.CreateDataset(filter = "[Nome] = 'John'")
      new_dataset = dataset.CreateDataset(filter = "[Nome] LIKE 'A'")
      new_dataset = dataset.CreateDataset(filter = f"({dataset.Filter}) AND [Nome] LIKE 'A'")
    Exclui o registro atual do conjunto de dados. Este método retorna True quando bem-sucedido.
Após esta operação o cursor é posicionado no registro imediatamente após o registro excluído. Se o registro excluído for o último do conjunto de dados, então o cursor é posicionado depois dele e a propriedade EOF retorna True.
svc.Delete(): bool
      oDataset.Delete()
    
      dataset.Delete()
    Exporta o valor de um campo binário do registro atual para o arquivo especificado.
Se o campo especificado não for binário ou não contiver dados, o arquivo de saída não será criado.
svc.ExportValueToFile(fieldname: str, filename: str, overwrite: bool): bool
fieldname: o nome do campo binário a ser exportado, como uma string sensível à caixa.
filename: O caminho completo para o arquivo a ser criado usando a notação definida na propriedade FileSystem.FileNaming.
overwrite: Defina este argumento como True para permitir que o arquivo de destino seja sobrescrito (Padrão = False).
No exemplo abaixo o conjunto de dados contém um campo denominado “Imagem” que deverá ser exportado para um arquivo de imagem.
      oDataset.ExportValueToFile("Imagem", "C:\minha_imagem.png", True)
    
      dataset.ExportValueToFile("Imagem", r"C:\minha_imagem.png", True)
    Retorna o conteúdo do conjunto de dados em uma matriz bidimensional, começando no primeiro registro após o registro atual.
Após a execução, o cursor é posicionado na última linha lida ou após o último registro do conjunto de dados, neste caso a propriedade EOF retorna True.
Este método pode ser usado para ler dados do conjunto de dados em blocos, cujo tamanho é definido pelo argumento maxrows.
A matriz retornada sempre terá duas dimensões, mesmo que o conjunto de dados contenha uma única coluna e um único registro.
svc.GetRows(header: bool, maxrows: int): any
header: Defina este argumento como True para fazer com que a primeira entrada no Array contenha os cabeçalhos das colunas (Padrão = False).
maxrows: Define o número máximo de registros a serem retornados. Se o número de registros existentes for menor que maxrows, então o tamanho do array retornado será igual ao número de registros restantes no conjunto de dados. Deixe este argumento em branco ou defina-o como zero para retornar todas as linhas do conjunto de dados (padrão = 0)
O exemplo a seguir lê um conjunto de dados em blocos de 100 linhas até que todo o conjunto de dados tenha sido lido.
      Dim arrChunk As Variant, lMaxRows As Long
      lMaxRows = 100
      Do
          arrChunk = oDataset.GetRows(MaxRows := lMaxRows)
          If UBound(arrChunk, 1) >= 0 Then
              ' ...
          End If
      Loop Until UBound(arrChunk, 1) < lMaxRows - 1
    
      max_rows = 100
      chunk = dataset.GetRows(maxrows = max_rows)
      while len(chunk) > 0:
          # ...
          chunk = dataset.GetRows(maxrows = max_rows)
    Retorna o valor do campo especificado do registro atual do conjunto de dados.
Se o campo especificado for binário, seu comprimento será retornado.
svc.GetValue(fieldname: str): any
fieldname: O nome do campo a ser retornado, como uma string sensível à caixa.
      currId = oDataset.GetValue(FieldName := "ID")
    
      curr_id = dataset.GetValue(fieldname = "ID")
    Insere um novo registro no final do conjunto de dados e inicializa seus campos com os valores especificados.
Se a chave primária do conjunto de dados for um valor automático, este método retornará o valor da chave primária do novo registro. Caso contrário, o método retornará 0 (quando bem-sucedido) ou -1 (quando não for bem-sucedido).
Os campos atualizáveis com valores não especificados são inicializados com seus valores padrão.
Se o campo especificado for binário, seu comprimento será retornado.
svc.Insert(pvargs: any): int
pvargs: Uma instância Dictionary contendo pares de nomes de campos e seus respectivos valores. Alternativamente, um número par de argumentos pode ser especificado alternando nomes de campos (como uma String) e seus valores.
Considere uma tabela chamada "Clientes" com 4 campos: "ID" (BigInt, valor automático e chave primária), "Nome" (VarChar), "Idade" (Integer), "Cidade" (VarChar).
O exemplo abaixo insere um novo registro neste conjunto de dados usando um objeto Dictionary.
      oDataset = oDatabase.CreateDataset("Clientes")
      oNewData = CreateScriptService("Dictionary")
      oNewData.Add("Nome", "João")
      oNewData.Add("Idade", 50)
      oNewData.Add("Cidade", "Curitiba")
      lNewID = oDataset.Insert(oNewData)
    O mesmo resultado pode ser alcançado passando todos os pares de campos e valores como argumentos:
      oDataset.Insert("Nome", "João", "Idade", 50, "Cidade", "Curitiba")
    
      dataset = database.CreateDataset("Clientes")
      new_data = {"Nome": "João", "Idade": 30, "Cidade": "Curitiba"}
      new_id = dataset.Insert(new_data)
    As seguintes chamadas são aceitas em Python:
      dataset.Insert("Nome", "João", "Idade", 50, "Cidade", "Curitiba")
      dataset.Insert(Nome = "João", Idade = 50, Cidade = "Curitiba")
    Move o cursor do conjunto de dados para o primeiro (com MoveFirst) ou para o último (com MoveLast) registro.
Este método retorna True quando for bem-sucedido.
Os registros excluídos são ignorados por este método.
svc.MoveFirst(): bool
svc.MoveLast(): bool
      oDataset.MoveFirst()
    
      dataset.MoveFirst()
    Move o cursor do conjunto de dados para frente (com MoveNext) ou para trás (com MovePrevious) por um determinado número de registros.
Este método retorna True quando for bem-sucedido.
Os registros excluídos são ignorados por este método.
svc.MoveNext(offset: int = 1): bool
svc.MovePrevious(offset: int = 1): bool
offset: Número de registros pelos quais o cursor deve ser movido para frente ou para trás. Este argumento pode ser um valor negativo (Padrão = 1).
      oDataset.MoveNext()
      oDataset.MoveNext(5)
    
      dataset.MoveNext()
      dataset.MoveNext(5)
    Recarrega o conjunto de dados a partir do banco de dados. As propriedades Filter e OrderBy podem ser definidas ao chamar este método.
Este método retorna True quando for bem-sucedido.
Recarregar o conjunto de dados é útil quando registros foram inseridos ou excluídos do banco de dados. Observe que os métodos CreateDataset e Reload executam funções semelhantes, porém Reload reutiliza a mesma instância da classe Dataset.
svc.Reload(opt filter: str, opt orderby: str): bool
filter: especifica a condição que os registros devem atender para serem incluídos no conjunto de dados retornado. Este argumento é expresso como uma instrução SQL WHERE sem a palavra-chave "WHERE". Se este argumento não for especificado, então o filtro usado no conjunto de dados atual será aplicado, caso contrário, o filtro atual será substituído por este argumento.
orderby: especifica a ordem do conjunto de dados como uma instrução SQL ORDER BY sem a palavra-chave "ORDER BY". Se este argumento não for especificado, então a ordem de classificação usada no conjunto de dados atual será aplicada; caso contrário, a ordem de classificação atual será substituída por este argumento.
      oDataset.Reload()
      oDataset.Reload(Filter := "[Nome] = 'João'", OrderBy := "Idade")
    
      dataset.Reload()
      dataset.Reload(Filter = "[Nome] = 'João'", OrderBy = "Idade")
    Atualize os valores dos campos especificados no registro atual.
Este método retorna True quando for bem-sucedido.
svc.Update(pvargs: any): bool
pvargs: Uma instância Dictionary contendo pares de nomes de campos e seus respectivos valores. Alternativamente, um número par de argumentos pode ser especificado alternando nomes de campos (como uma String) e seus valores.
O exemplo abaixo atualiza o registro atual usando um objeto Dictionary.
      oNewValues = CreateScriptService("Dictionary")
      oNewValues.Add("Idade", 51)
      oNewValues.Add("Cidade", "Florianópolis")
      oDataset.Update(oNewValues)
    O mesmo resultado pode ser alcançado passando todos os pares de campos e valores como argumentos:
      oDataset.Update("Idade", 51, "Cidade", "Florianópolis")
    
      new_values = {"Idade": 51, "Cidade": "Florianópolis"}
      dataset.Update(new_values)
    
      dataset.Update("Idade", 51, "Cidade", "Florianópolis")
      dataset.Update(Idade = 51, Cidade = "Florianópolis")