Aide LibreOffice 25.2
Le service Dataset est utilisé pour représenter des données tabulaires produites par une base de données. Avec ce service, il est possible de :
Naviguer et accéder aux données dans un ensemble de données.
Mettre à jour, insérer et supprimer des enregistrements dans un ensemble de données.
La mise à jour et l'insertion d'enregistrements à l'aide du service Dataset sont plus lentes qu'à l'aide d'instructions SQL. Lors de la mise à jour ou de l'insertion d'un grand nombre d'enregistrements, il est recommandé d'utiliser des instructions SQL au lieu d'utiliser les méthodes de ce service.
Avant d'utiliser le service Dataset, la bibliothèque ScriptForge doit être chargée ou importée :
Le service Dataset est invoqué à l'aide de la méthode CreateDataset, qui peut être appelée soit à partir d'une instance de service Database, soit à partir d'un autre instance Dataset
L'exemple suivant crée un Dataset à partir de la table "Customers" stockée dans un fichier de base de données.
    oDatabase = CreateScriptService("Database", "C:\MyDatabase.odb")
    oDataset = oDatabase.CreateDataset("Customers")
    With oDataset
        Do While .MoveNext()
            oValues = .Values()
            ' ...
        Loop
        .CloseDataset()
    End With
  Lors de la création du Dataset, l'enregistrement courant est positionné avant le premier enregistrement.
L'exemple ci-dessous crée une instance Dataset en filtrant l'ensemble de données d'origine.
    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'")
  | Nom | En lecture seule | Type | Description | 
|---|---|---|---|
| BOF | Non | Boolean | Renvoie True si la position actuelle de l'enregistrement est avant le premier enregistrement de l'ensemble de données, sinon renvoie False. Définissez cette propriété sur True pour déplacer le curseur au début de l'ensemble de données. La définition de cette propriété sur False est ignorée. | 
| DefaultValues | Oui | Service Dictionary | Renvoie un Dictionary avec les valeurs par défaut utilisées pour chaque champ de l'ensemble de données. Les champs ou colonnes de l'ensemble de données sont les clés du dictionnaire. Les types de champs de base de données sont convertis en leurs types de données Basic/Python correspondants. Lorsque le type de champ n'est pas défini, la valeur par défaut est Null si le champ peut être nul ou Vide. | 
| EOF | No | Boolean | Renvoie True si la position actuelle de l'enregistrement est après le dernier enregistrement de l'ensemble de données, sinon renvoie False. Définissez cette propriété sur True pour déplacer le curseur à la fin de l'ensemble de données. La définition de cette propriété sur False est ignorée. | 
| Fields | Oui | Array | Renvoie une Array contenant les noms de tous les champs de l'ensemble de données | 
| Filter | Oui | String | Renvoie le filtre appliqué en plus des éventuelles clauses WHERE dans l'instruction SQL initiale. Cette propriété est exprimée sous la forme d'une clause WHERE sans le mot clé "WHERE". | 
| OrderBy | Oui | String | Renvoie la clause de tri qui remplace l'éventuelle clause ORDER BY présente dans l'instruction SQL initiale. Cette propriété est exprimée sous la forme d'une clause ORDER BY sans les mots-clés "ORDER BY". | 
| ParentDatabase | Oui | Service Database | Renvoie l'instance Database correspondant à la base de données parent de l'ensemble de données actuel. | 
| RowCount | Oui | Long | Renvoie le nombre exact d'enregistrements dans l'ensemble de données. Notez que l'évaluation de cette propriété implique de parcourir l'ensemble des données, ce qui peut être coûteux en fonction de la taille de l'ensemble de données. | 
| RowNumber | Oui | Long | Renvoie le numéro de l'enregistrement actuel commençant à 1. Renvoie 0 si cette propriété est inconnue. | 
| Source | Oui | String | Renvoie la source de l'ensemble de données. Il peut s'agir d'un nom de table, d'un nom de requête ou d'une instruction SQL. | 
| SourceType | Oui | String | Renvoie la source de l'ensemble de données. Il peut s'agir de l'une des valeurs de chaîne suivantes : TABLE, QUERY ou SQL. | 
| UpdatableFields | Oui | Array | Renvoie une Array contenant les noms des champs de l'ensemble de données pouvant être mis à jour. | 
| Values | Oui | Array | Renvoie un Dictionary contenant les paires (nom du champ : valeur) de l'enregistrement actuel dans l'ensemble de données. | 
| XRowSet | Oui | Objet UNO | Renvoie l'objet UNO com.sun.star.sdb.RowSet représentant l'ensemble de données. | 
| Liste des méthodes dans le service Dataset | ||
|---|---|---|
Ferme l'ensemble de données actuel. Cette méthode renvoie True en cas de succès.
Il est recommandé de fermer le jeu de données après son utilisation pour libérer des ressources.
svc.CloseDataset(): bool
      oDataset = oDatabase.CreateDataset("MyTable")
      ' ...
      oDataset.CloseDataset()
    
      dataset = database.CreateDataset("MyTable")
      # ...
      dataset.CloseDataset()
    Renvoie une instance de service Dataset à partir d'un ensemble de données existant en appliquant le filtre spécifié et les instructions ORDER BY .
svc.CreateDataset(opt filter: str, opt orderby: str): svc
filter : spécifie la condition à laquelle les enregistrements doivent correspondre pour être inclus dans l'ensemble de données renvoyé. Cet argument est exprimé sous la forme d'une instruction SQL WHERE sans le mot clé "WHERE". Si cet argument n'est pas spécifié, alors le filtre utilisé dans le jeu de données actuel est appliqué, sinon le filtre actuel est remplacé par cet argument.
orderby : spécifie l'ordre de l'ensemble de données sous la forme d'une instruction SQL ORDER BY sans le mot clé "ORDER BY". Si cet argument n'est pas spécifié, alors l'ordre de tri utilisé dans l'ensemble de données actuel est appliqué, sinon l'ordre de tri actuel est remplacé par cet argument.
      ' Utiliser une chaîne vide pour supprimer le filtre actuel
      oNewDataset = oDataset.CreateDataset(Filter := "")
      ' Exemples de filtres usuels
      oNewDataset = oDataset.CreateDataset(Filter := "[Name] = 'John'")
      oNewDataset = oDataset.CreateDataset(Filter := "[Name] LIKE 'A'")
      ' Il est possible d'ajouter des conditions supplémentaires au filtre actuel
      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'")
    Supprime l'enregistrement actuel de l'ensemble de données. Cette méthode renvoie True en cas de succès.
Après cette opération, le curseur est positionné sur l'enregistrement immédiatement après l'enregistrement supprimé. Si l'enregistrement supprimé est le dernier de l'ensemble de données, alors le curseur est positionné après lui et la propriété EOF renvoie True.
svc.Delete(): bool
      oDataset.Delete()
    
      dataset.Delete()
    Exporte la valeur d'un champ binaire de l'enregistrement courant vers le fichier spécifié.
Si le champ spécifié n'est pas binaire ou s'il ne contient aucune donnée, alors le fichier de sortie n'est pas créé.
svc.ExportValueToFile(fieldname: str, filename: str, overwrite: bool): bool
fieldname : le nom du champ binaire à exporter, sous forme de chaîne sensible à la casse.
filename : le chemin complet du fichier à créer en utilisant la notation définie dans la propriété FileSystem.FileNaming.
overwrite : définissez cet argument sur True pour permettre l'écrasement du fichier de destination (par défaut = False).
Dans l'exemple ci-dessous, l'ensemble de données contient un champ nommé "Picture" qui doit être exporté vers un fichier image.
      oDataset.ExportValueToFile("Picture", "C:\my_image.png", True)
    
      dataset.ExportValueToFile("Picture", r"C:\my_image.png", True)
    Renvoie le contenu de l'ensemble de données dans une matrice à 2 dimensions, en commençant par le premier enregistrement après l'enregistrement actuel.
Après l'exécution, le curseur est positionné sur la ligne qui a été lue pour la dernière fois ou après le dernier enregistrement de l'ensemble de données, auquel cas la propriété EOF renvoie True.
Cette méthode peut être utilisée pour lire les données de l'ensemble de données en morceaux, dont la taille est définie par l'argument maxrows.
La matrice renvoyée aura toujours deux dimensions, même si l'ensemble de données contient une seule colonne et un seul enregistrement.
svc.GetRows(header: bool, maxrows: int): any
header : définissez cet argument sur True pour que la première entrée de Array contienne les en-têtes de colonnes (par défaut = False).
maxrows : définit le nombre maximum d'enregistrements à renvoyer. Si le nombre d'enregistrements existants est inférieur à maxrows, alors la taille de la matrice renvoyée sera égale au nombre d'enregistrements restants dans l'ensemble de données. Laissez cet argument vide ou définissez-le sur zéro pour renvoyer toutes les lignes de l'ensemble de données (par défaut = 0)
L'exemple suivant lit un ensemble de données par morceaux de 100 lignes jusqu'à ce que tout l'ensemble de données ait été lu.
      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)
    Renvoie la valeur du champ spécifié à partir de l'enregistrement actuel de l'ensemble de données.
Si le champ spécifié est binaire, sa longueur est renvoyée.
svc.GetValue(fieldname: str): any
fieldname : le nom du champ à renvoyer, sous forme de chaîne sensible à la casse.
      currId = oDataset.GetValue(FieldName := "ID")
    
      curr_id = dataset.GetValue(fieldname = "ID")
    Insère un nouvel enregistrement à la fin de l'ensemble de données et initialise ses champs avec les valeurs spécifiées.
Si la clé primaire de l'ensemble de données est une valeur automatique, cette méthode renvoie la valeur de clé primaire du nouvel enregistrement. Sinon, la méthode renverra 0 (en cas de succès) ou -1 (en cas d'échec).
Les champs pouvant être mis à jour avec des valeurs non spécifiées sont initialisés avec leurs valeurs par défaut.
Si le champ spécifié est binaire, sa longueur est renvoyée.
svc.Insert(pvargs: any): int
pvargs : un Dictionary contenant des paires de noms de champs et leurs valeurs respectives. Alternativement, un nombre pair d'arguments peut être spécifié en alternant les noms de champs (sous forme de String) et leurs valeurs.
Considérons une table nommée "Customers" avec 4 champs : "ID" (BigInt, valeur automatique et clé primaire), "Name" (VarChar), "Age" (Integer), "City" (VarChar).
L'exemple ci-dessous insère un nouvel enregistrement dans cet ensemble de données à l'aide de Dictionary.
      oDataset = oDatabase.CreateDataset("Customers")
      oNewData = CreateScriptService("Dictionary")
      oNewData.Add("Name", "John")
      oNewData.Add("Age", 50)
      oNewData.Add("City", "Chicago")
      lNewID = oDataset.Insert(oNewData)
    Le même résultat peut être obtenu en passant toutes les paires de champs et de valeurs comme arguments :
      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)
    Les appels suivants sont acceptés en Python :
      dataset.Insert("Name", "John", "Age", 50, "City", "Chicago")
      dataset.Insert(Name = "John", Age = 50, City = "Chicago")
    Déplace le curseur de l'ensemble de données vers le premier (avec MoveFirst) ou vers le dernier (avec MoveLast) enregistrement.
Cette méthode renvoie True en cas de succès.
Les enregistrements supprimés sont ignorés par cette méthode.
svc.MoveFirst(): bool
svc.MoveLast(): bool
      oDataset.MoveFirst()
    
      dataset.MoveFirst()
    Déplace le curseur de l'ensemble de données vers l'avant (avec MoveNext) ou vers l'arrière (avec MovePrevious) d'un nombre donné d'enregistrements.
Cette méthode renvoie True en cas de succès.
Les enregistrements supprimés sont ignorés par cette méthode.
svc.MoveNext(offset: int = 1): bool
svc.MovePrevious(offset: int = 1): bool
offset : nombre d'enregistrements dont le curseur doit être déplacé vers l'avant ou vers l'arrière. Cet argument peut être une valeur négative (par défaut = 1).
      oDataset.MoveNext()
      oDataset.MoveNext(5)
    
      dataset.MoveNext()
      dataset.MoveNext(5)
    Recharge l'ensemble de données à partir de la base de données. Les propriétés Filter et OrderBy peuvent être définies lors de l'appel de cette méthode.
Cette méthode renvoie True en cas de succès.
Le rechargement de l'ensemble de données est utile lorsque des enregistrements ont été insérés ou supprimés de la base de données. Notez que les méthodes CreateDataset et Reload exécutent des fonctions similaires, cependant Reload réutilise la même instance de classe Dataset.
svc.Reload(opt filter: str, opt orderby: str): bool
filter : spécifie la condition à laquelle les enregistrements doivent correspondre pour être inclus dans l'ensemble de données renvoyé. Cet argument est exprimé sous la forme d'une instruction SQL WHERE sans le mot clé "WHERE". Si cet argument n'est pas spécifié, alors le filtre utilisé dans le jeu de données actuel est appliqué, sinon le filtre actuel est remplacé par cet argument.
orderby : spécifie l'ordre de l'ensemble de données sous la forme d'une instruction SQL ORDER BY sans le mot clé "ORDER BY". Si cet argument n'est pas spécifié, alors l'ordre de tri utilisé dans l'ensemble de données actuel est appliqué, sinon l'ordre de tri actuel est remplacé par cet argument.
      oDataset.Reload()
      oDataset.Reload(Filter := "[Name] = 'John'", OrderBy := "Age")
    
      dataset.Reload()
      dataset.Reload(Filter = "[Name] = 'John'", OrderBy = "Age")
    Mettre à jour les valeurs des champs spécifiés dans l'enregistrement actuel.
Cette méthode renvoie True en cas de succès.
svc.Update(pvargs: any): bool
pvargs : un Dictionary contenant des paires de noms de champs et leurs valeurs respectives. Alternativement, un nombre pair d'arguments peut être spécifié en alternant les noms de champs (sous forme de String) et leurs valeurs.
L'exemple ci-dessous met à jour l'enregistrement actuel à l'aide d'un Dictionary.
      oNewValues = CreateScriptService("Dictionary")
      oNewValues.Add("Age", 51)
      oNewValues.Add("City", "New York")
      oDataset.Update(oNewValues)
    Le même résultat peut être obtenu en passant toutes les paires de champs et de valeurs comme arguments :
      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")