Nápověda LibreOffice 25.2
Služba Dataset se používá k tomu, aby reprezentovala tabulková data z databáze. Pomocí této služby je možné:
Procházet datovou sadu a přistupovat k jejím datům.
V datové sadě aktualizovat, vkládat a odstraňovat záznamy.
Aktualizace a vkládání záznamů pomocí služby Dataset je pomalejší než použití SQL příkazů. Při aktualizaci nebo vkládání značného množství záznamů je doporučeno použít SQL příkazy místo metod této služby.
Před používáním služby Dataset je nutné načíst či naimportovat knihovnu ScriptForge pomocí:
Instance služby Dataset je vytvořena metodou CreateDataset, kterou lze zavolat buď z instance služby Database, nebo z jiné instance služby Dataset.
V následujících příkladech je instance služby Dataset vytvořena z tabulky „Customers“ uložené v databázovém souboru.
    oDatabase = CreateScriptService("Database", "C:\MyDatabase.odb")
    oDataset = oDatabase.CreateDataset("Customers")
    With oDataset
        Do While .MoveNext()
            oValues = .Values()
            ' ...
        Loop
        .CloseDataset()
    End With
  Po vytvoření instance Dataset je aktuální pozice záznamu nastavena před první záznam.
V následujícím příkladu se vytvoří instance služby Dataset filtrováním původní datové sady.
    oNewDataset = oDataset.CreateDataset(Filter := "[City]='New York'")
  
    database = CreateScriptService("Database", r"C:\MyDatabase.odb")
    dataset = database.CreateDataset("Customers")
    while dataset.MoveNext():
        values = dataset.Values
        # ...
    dataset.CloseDataset()
  
    new_dataset = dataset.CreateDataset(filter = "[City]='New York'")
  | Název | Pouze pro čtení | Typ | Popis | 
|---|---|---|---|
| BOF | ne | Boolean | Vrátí True, pokud je aktuální pozice záznamu před prvním záznamem datové sady. V opačném případě vrátí False. Nastavením této vlastnosti na True přesunete ukazatel na začátek datové sady. Nastavení na False se ignoruje. | 
| DefaultValues | ano | služba Dictionary | Vrátí Dictionary s výchozími hodnotami použitými pro každé pole datové sady. Pole (sloupce) datové sady jsou klíči slovníku. Typy databázových polí se převádějí na odpovídající datové typy Basicu/Pythonu. Není-li typ pole definován, výchozí hodnotou je Null, pokud lze pole vynulovat, nebo Empty. | 
| EOF | ne | Boolean | Vrátí True, pokud je aktuální pozice záznamu za posledním záznamem datové sady. V opačném případě vrátí False. Nastavením této vlastnosti na True přesunete ukazatel na konec datové sady. Nastavení na False se ignoruje. | 
| Fields | ano | Array | Vrátí Array obsahující názvy všech polí datové sady. | 
| Filter | ano | String | Vrátí filtr použitý spolu s případnými klauzulemi WHERE v inicializačním SQL příkazu. Tato vlastnost je vyjádřena jako klauzule WHERE bez klíčového slova „WHERE“. | 
| OrderBy | ano | String | Vrátí klauzuli pro řazení, která případně nahrazuje klauzuli ORDER BY obsaženou v inicializačním SQL příkazu. Tato vlastnost je vyjádřena jako klauzule ORDER BY bez klíčových slov „ORDER BY“. | 
| ParentDatabase | ano | služba Database | Vrátí instanci služby Database odpovídající rodičovské databázi pro aktuální datovou sadu. | 
| RowCount | ano | Long | Vrátí přesný počet záznamů datové sady. Vyhodnocení této vlastnosti vyžaduje projití celé datové sady, což může být v závislosti na její velikosti náročné. | 
| RowNumber | ano | Long | Vrátí číslo začínající od 1 pro aktuální záznam. Je-li tato vlastnost neznámá, vrátí 0. | 
| Source | ano | String | Vrátí zdroj datové sady. Může se jednat o název tabulky, název dotazu nebo SQL příkaz. | 
| SourceType | ano | String | Vrátí zdroj datové sady. Jedná se o některý z následujících řetězců:TABLE, QUERY nebo SQL. | 
| UpdatableFields | ano | Array | Vrátí Array obsahující ty názvy polí datové sady, které lze aktualizovat. | 
| Values | ano | Array | Vrátí Dictionary obsahující dvojice (název pole: hodnota) pro aktuální záznam datové sady. | 
| XRowSet | ano | objekt UNO | Vrátí objekt UNO com.sun.star.sdb.RowSet představující datovou sadu. | 
| Seznam metod služby Dataset | ||
|---|---|---|
Zavře aktuální datovou sadu. V případě úspěšného uzavření vrátí metoda True.
Po použití se doporučuje datovou sadu uzavřít kvůli uvolnění zdrojů.
svc.CloseDataset(): bool
      oDataset = oDatabase.CreateDataset("MyTable")
      ' ...
      oDataset.CloseDataset()
    
      dataset = database.CreateDataset("MyTable")
      # ...
      dataset.CloseDataset()
    Vrátí instanci služby Dataset ze stávající datové sady po použití zadaného filtru a příkazů ORDER BY.
svc.CreateDataset(opt filter: str, opt orderby: str): svc
filter: Určuje podmínku, kterou musí záznamy splňovat, aby byly zahrnuty do vrácené datové sady. Tento argument je vyjádřen jako SQL příkaz WHERE bez klíčového slova „WHERE“. Pokud tento argument není zadán, použije se filtr aktuální datové sady, v opačném případě bude tento aktuální filtr nahrazen tímto argumentem.
orderby: Určuje řazení datové sady jako SQL příkaz ORDER BY bez klíčového slova „ORDER BY“. Pokud tento argument není zadán, použije se řazení aktuální datové sady, v opačném případě bude toto aktuální řazení nahrazeno tímto argumentem.
      ' Aktuální filtr odstraníte prázdným řetězcem
      oNewDataset = oDataset.CreateDataset(Filter := "")
      ' Příklady běžných filtrů
      oNewDataset = oDataset.CreateDataset(Filter := "[Name] = 'Jan'")
      oNewDataset = oDataset.CreateDataset(Filter := "[Name] LIKE 'A'")
      ' K aktuálnímu filtru lze přidat další podmínky
      oNewDataset = oDataset.CreateDataset(Filter := "(" & oDataset.Filter & ") AND [Name] LIKE 'A'")
    
      new_dataset = dataset.CreateDataset(filter = "")
      new_dataset = dataset.CreateDataset(filter = "[Name] = 'John'")
      new_dataset = dataset.CreateDataset(filter = "[Name] LIKE 'A'")
      new_dataset = dataset.CreateDataset(filter = f"({dataset.Filter}) AND [Name] LIKE 'A'")
    Smaže z datové sady aktuální záznam. V případě úspěšného smazání metoda vrátí True.
Po této operaci se ukazatel umístí na záznam bezprostředně následující za smazaným záznamem. Pokud je smazaný záznam posledním v datové sadě, ukazatel se umístí za něj a vlastnost EOF se nastaví na True.
svc.Delete(): bool
      oDataset.Delete()
    
      dataset.Delete()
    Vyexportuje hodnotu binární pole aktuálního záznamu do zadaného souboru.
Jestliže zadané pole není binární nebo neobsahuje žádná data, výstupní soubor se nevytvoří.
svc.ExportValueToFile(fieldname: str, filename: str, overwrite: bool): bool
fieldname: Název binárního pole, které se má vyexportovat, jako řetězec, u něhož se rozlišuje velikost písmen.
filename: Úplná cesta k souboru, který se má vytvořit, v zápisu určeném vlastností FileSystem.FileNaming.
overwrite: Nastavte tento argument na True, chcete-li umožnit přepsání cílového souboru (výchozí = False).
V následujícím příkladu obsahuje datová sada pole pojmenované „Picture“, které by se mělo vyexportovat do souboru s obrázkem.
      oDataset.ExportValueToFile("Picture", "C:\my_image.png", True)
    
      dataset.ExportValueToFile("Picture", r"C:\my_image.png", True)
    Vrátí hodnoty datové sady ve dvourozměrném poli začínajícím od prvního záznamu po aktuálním záznamu.
Po vykonání se ukazatel umístí na řádek, který byl naposledy přečten, nebo za poslední záznam datové sady, přičemž se vlastnost EOF nastaví na hodnotu True.
Tuto metodu je možné použít pro čtení dat z datové sady po částech, jejichž velikost je určena argumentem maxrows.
Vrácené pole bude mít vždy dva rozměry, a to i tehdy, když datová sada obsahuje jediný sloupec a jediný záznam.
svc.GetRows(header: bool, maxrows: int): any
header: Nastavte tento argument na True, chcete-li, aby první položka Array obsahovala záhlaví sloupců (výchozí = False).
maxrows: Určuje maximální počet vrácených záznamů. Jestliže je počet existujících záznamů menší, velikost vráceného pole bude odpovídat počtu zbývajících záznamů v datové sadě. Chcete-li vrátit všechny řádky datové sady, ponechte tento argument prázdný nebo jej nastavte na nulu (výchozí = 0).
V následujícím příkladu je čtena celá datová sada, a to postupně po částech o 100 řádcích.
      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)
    Vrátí z aktuálního záznamu datové sady hodnotu zadaného pole.
Jestliže je zadané pole binární, vrátí se jeho délka.
svc.GetValue(fieldname: str): any
fieldname: Název pole, které se má vrátit, jako řetězec, u něhož se rozlišuje velikost písmen.
      currId = oDataset.GetValue(FieldName := "ID")
    
      curr_id = dataset.GetValue(fieldname = "ID")
    Vloží na konec datové sady nový záznam a inicializuje jeho pole zadanými hodnotami.
Pokud má primární klíč datové sady automatickou hodnotu, vrátí tato metoda hodnotu primárního klíče nového záznamu. V opačném případě vrátí 0 (v případě úspěšného vložení) nebo -1 (v případě neúspěšného vložení).
Pole, která lze aktualizovat, ale nemají zadané hodnoty, budou inicializována výchozími hodnotami.
Jestliže je zadané pole binární, vrátí se jeho délka.
svc.Insert(pvargs: any): int
pvargs: Dictionary obsahující dvojice názvů polí a jejich hodnot. Alternativně je možné zadat sudý počet argumentů představujících názvy polí (typu String) a jejich hodnoty.
Tabulka s názvem „Customers“ má 4 pole: „ID“ (BigInt, automatická hodnota a primární klíč), „Name“ (VarChar), „Age“ (Integer) a „City“ (VarChar).
V následujícím příkladu se do této datové sady vloží nový záznam pomocí Dictionary.
      oDataset = oDatabase.CreateDataset("Customers")
      oNewData = CreateScriptService("Dictionary")
      oNewData.Add("Name", "John")
      oNewData.Add("Age", 50)
      oNewData.Add("City", "Chicago")
      lNewID = oDataset.Insert(oNewData)
    Téhož výsledku je možné dosáhnout předáním všech dvojic polí a hodnot:
      oDataset.Insert("Name", "John", "Age", 50, "City", "Chicago")
    
      dataset = database.CreateDataset("Customers")
      new_data = {"Name": "John", "Age": 30, "City": "Chicago"}
      new_id = dataset.Insert(new_data)
    V Pythonu je možné použít následující volání:
      dataset.Insert("Name", "John", "Age", 50, "City", "Chicago")
      dataset.Insert(Name = "John", Age = 50, City = "Chicago")
    Přesune ukazatel v datové sadě na první (u MoveFirst) nebo na poslední (u MoveLast) záznam.
V případě úspěšného přesunutí vrátí metoda True.
Tato metoda ignoruje smazané záznamy.
svc.MoveFirst(): bool
svc.MoveLast(): bool
      oDataset.MoveFirst()
    
      dataset.MoveFirst()
    Přesune ukazatel v datové sadě o zadaný počet záznamů vpřed (u MoveNext) nebo vzad (u MovePrevious).
V případě úspěšného přesunutí vrátí metoda True.
Tato metoda ignoruje smazané záznamy.
svc.MoveNext(offset: int = 1): bool
svc.MovePrevious(offset: int = 1): bool
offset: Počet záznamů, o který se má ukazatel přesunout vpřed nebo vzad. Tento argument může být záporný (výchozí = 1).
      oDataset.MoveNext()
      oDataset.MoveNext(5)
    
      dataset.MoveNext()
      dataset.MoveNext(5)
    Znovu načte datovou sadu z databáze. Při volání této metody lze určit vlastnosti Filter a OrderBy.
V případě úspěšného načtení vrátí metoda True.
Opětovné načtení je užitečné, jestliže byly do databáze vloženy nebo z ní odstraněny záznamy. Metody CreateDataset a Reload provádějí podobné operace, metoda Reload však znovu používá stejnou instanci třídy Dataset.
svc.Reload(opt filter: str, opt orderby: str): bool
filter: Určuje podmínku, kterou musí záznamy splňovat, aby byly zahrnuty do vrácené datové sady. Tento argument je vyjádřen jako SQL příkaz WHERE bez klíčového slova „WHERE“. Pokud tento argument není zadán, použije se filtr aktuální datové sady, v opačném případě bude tento aktuální filtr nahrazen tímto argumentem.
orderby: Určuje řazení datové sady jako SQL příkaz ORDER BY bez klíčového slova „ORDER BY“. Pokud tento argument není zadán, použije se řazení aktuální datové sady, v opačném případě bude toto aktuální řazení nahrazeno tímto argumentem.
      oDataset.Reload()
      oDataset.Reload(Filter := "[Name] = 'John'", OrderBy := "Age")
    
      dataset.Reload()
      dataset.Reload(Filter = "[Name] = 'John'", OrderBy = "Age")
    Aktualizuje v aktuálním záznamu hodnoty zadaných polí.
V případě úspěšné aktualizace vrátí metoda True.
svc.Update(pvargs: any): bool
pvargs: Dictionary obsahující dvojice názvů polí a jejich hodnot. Alternativně je možné zadat sudý počet argumentů představujících názvy polí (typu String) a jejich hodnoty.
V následujícím příkladu je aktuální záznam aktualizován pomocí Dictionary.
      oNewValues = CreateScriptService("Dictionary")
      oNewValues.Add("Age", 51)
      oNewValues.Add("City", "New York")
      oDataset.Update(oNewValues)
    Téhož výsledku je možné dosáhnout předáním všech dvojic polí a hodnot:
      oDataset.Update("Age", 51, "City", "New York")
    
      new_values = {"Age": 51, "City": "New York"}
      dataset.Update(new_values)
    
      dataset.Update("Age", 51, "City", "New York")
      dataset.Update(Age = 51, City = "New York")