Помощ за LibreOffice 25.2
Услугата Database предоставя достъп до вградени или описани в документи на Base бази от данни. Тази услуга предлага методи за:
получаване на достъп до таблици в база от данни
стартиране на заявки SELECT и изчисляване на агрегатни функции
изпълнение на оператори за действия на SQL като INSERT, UPDATE, DELETE и т.н.
Всеки екземпляр на услугата Database представя единична база от данни и дава достъп до нейните таблици, заявки и данни.
Тази услуга не предлага достъп до формуляри или справки в документа на Base, който съдържа базата от данни. За достъп до формуляри в документи на Base вижте метода FormDocuments на услугата Base.
Целият обмен между тази услуга и базата от данни се извършва само посредством SQL.
Оператори на SQL може да се изпълняват в пряк или непряк режим. В пряк режим операторът се предава към СУБД без проверка на синтаксиса или преглеждане.
Предлаганите интерфейси включват прости списъци на таблиците и заявките, както и достъп до данните в базата от данни.
За да направите операторите на SQL по-четливи, може да ограждате имената на таблици, заявки и полета с квадратни скоби „[ ]“, вместо с други ограждащи знаци, които може да се поддържат само от определени системи за управление на бази от данни (СУБД). Но имайте предвид, че в този контекст ограждащите знаци са задължителни.
По подразбиране базата от данни обработва трансакциите в режим на автоматично фиксиране, което означава, че след всеки оператор на SQL се извършва фиксиране на промените.
Използвайте метода SetTransactionMode, за да промените подразбираното поведение – това позволява ръчно фиксиране и връщане.
Методите Commit и Rollback служат за отделяне на трансакциите.
В LibreOffice има пет вида режими на изолиране на трансакциите, както е дефинирано в групата константи com.sun.star.sdbc.TransactionIsolation:
| Константа | Стойност | Интерпретация | 
|---|---|---|
| NONE | 0 | Обработката на трансакции е деактивирана и базата от данни е в подразбирания режим на автоматично фиксиране. | 
| READ_UNCOMMITTED | 1 | Може да се случи прочитане на неактуални данни, неповтаряемо прочитане и фантомно прочитане. Ако някой ред бъде променен от трансакция, друга трансакция ще може да прочете промените дори ако още не са фиксирани. | 
| READ_COMMITTED | 2 | Прочитането на неактуални данни се предотвратява, но все пак може да се случи неповтаряемо или фантомно прочитане. Това ниво предотвратява прочитането на редове с нефиксирани промени. | 
| REPEATABLE_READ | 4 | Предотвратява се прочитане на неактуални данни и неповтаряемо прочитане. Може обаче да се случи фантомно прочитане. Предотвратява се както прочитането на нефиксирани данни, така и връщането на различни резултати от две прочитания в рамките на една трансакция. | 
| SERIALIZABLE | 8 | Предотвратява се прочитане на неактуални данни, неповтаряемо прочитане и фантомно прочитане. Освен ограниченията от предишното ниво се гарантира и че наборът от записи, който отговаря на дадена клауза WHERE, остава непроменен в рамките на трансакцията. | 
Прочетете страницата в Уикипедия Isolation in Database Systems (на английски), за да научите повече относно трансакционната цялост.
Преди да използвате услугата Database, библиотеката ScriptForge трябва да бъде заредена или импортирана:
За да създадете екземпляр на услугата Database, може да използвате метода CreateScriptService:
CreateScriptService("SFDatabases.Database", [filename: str], [registrationname], [readonly], [user, [password]]): svc
В описания по-горе синтаксис можете да използвате или "SFDatabases.Database", или просто "Database" като първи аргумент на метода CreateScriptService.
filename: името на файла на Base. То трябва да следва нотацията, зададена с SF_FileSystem.FileNaming.
registrationname: името на регистрирана база от данни. Ако е подаден filename, този аргумент не трябва да се използва.
Обратно, ако е зададен registrationname, параметърът filename не трябва да е дефиниран.
readonly: определя дали базата от данни да се отвори само за четене (подразбира се True).
user, password: допълнителни параметри на връзката към сървъра на базата от данни.
      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDatabase as Object
      Set myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      ' Изпълняване на заявки, оператори на SQL, ...
      myDatabase.CloseDatabase()
    
      from scriptforge import CreateScriptService
      myDatabase = CreateScriptService("Database", "/home/user/Documents/myDB.odb")
      # Изпълняване на заявки, оператори на SQL, ...
      myDatabase.CloseDatabase()
    Достъпът до базата от данни, свързана с документ на Base, е възможен и чрез услугата ScriptForge.UI, както е показано в следващите примери:
      Dim myDoc As Object, myDatabase As Object, ui As Object
      Set ui = CreateScriptService("UI")
      Set myDoc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      ' Потребителят (user) и паролата (password) се подават по-долу, ако е необходимо.
      Set myDatabase = myDoc.GetDatabase()
      ' Изпълняване на заявки, оператори на SQL, ...
      myDatabase.CloseDatabase()
      myDoc.CloseDocument()
    
      ui = CreateScriptService("UI")
      doc = ui.OpenBaseDocument("/home/user/Documents/myDB.odb")
      # Потребителят (user) и паролата (password) се подават по-долу, ако е необходимо.
      myDatabase = doc.GetDatabase()
      # Изпълняване на заявки, оператори на SQL, ...
      myDatabase.CloseDatabase()
      doc.CloseDocument()
    Методът GetDatabase, използван в горния пример, е част от услугата Base на ScriptForge.
| Име | Само за четене | Тип | Описание | 
|---|---|---|---|
| Queries | Да | Масив от низове | Списъкът от съхранени заявки. | 
| Tables | Да | Масив от низове | Списъкът от съхранени таблици. | 
| XConnection | Да | UNO обектът, представящ текущата връзка с база от данни. | |
| XMetaData | Да | UNO обектът, представящ метаданните, които описват системните атрибути на базата от данни. | 
| Списък с методи на услугата Database | ||
|---|---|---|
Затваря текущата връзка с база от данни.
db.CloseDatabase()
    myDatabase.CloseDatabase() ' Basic
  
    myDatabase.CloseDatabase() # Python
  Фиксира всички актуализации, извършени след предишното извикване на Commit или Rollback.
Този метод се игнорира, ако фиксиранията се извършват автоматично след всеки оператор на SQL, т.е. ако базата от данни е в режим на автоматично фиксиране.
db.Commit()
      ' Задаваме ниво на трансакциите REPEATABLE_READ.
      myDB.SetTransactionMode(4)
      myDB.RunSql("UPDATE ...")
      myDB.Commit()
      myDB.RunSql("DELETE ...")
      ' Проверяваме някакво условие преди фиксирането.
      If bSomeCondition Then
          myDB.Commit()
      Else
          myDB.Rollback()
      End If
      ' Възстановяваме режима на автоматично фиксиране.
      myDB.SetTransactionMode()
    
      myDB.SetTransactionMode(4)
      myDB.RunSql("UPDATE ...")
      myDB.Commit()
      myDB.RunSql("DELETE ...")
      if some_condition:
          myDB.Commit()
      else:
          myDB.Rollback()
      myDB.SetTransactionMode()
    Създава екземпляр на услугата Dataset на базата на таблица, заявка или оператор SELECT на SQL.
db.CreateDataset(sqlcommand: str, opt directsql: bool, opt filter: str, opt orderby: str): svc
sqlcommand: име на таблица, име на заявка или валиден оператор SELECT на SQL. Идентификаторите може да са оградени с квадратни скоби. В този аргумент се различават малки и главни букви.
directsql: задайте на този аргумент стойност True, за да изпратите оператора директно към системата за управление на базата от данни без предварителна обработка от LibreOffice (подразбира се False).
filter: указва условието, на което трябва да отговарят записите, за да бъдат включени в резултатния набор. Този аргумент е във вида на клауза WHERE без ключовата дума WHERE.
orderby: указва подреждането на съвкупността от данни като клауза ORDER BY на SQL без ключовата дума ORDER BY.
Следващите примери на Basic и Python връщат набор от данни със записи от таблица с име Customers.
      oDataset = myDatabase.CreateDataset("Customers", Filter := "[Name] LIKE 'A'")
    
      dataset = myDatabase.CreateDataset("Customers", Filter = "[Name] LIKE 'A'")
    Изчислява дадената агрегатна функция върху поле или израз от таблица.
По желание може да се зададе клауза на SQL WHERE като филтър, който да бъде приложен преди агрегатната функция.
db.DAvg(expression: str, tablename: str, [criteria: str]): any
db.DCount(expression: str, tablename: str, [criteria: str]): any
db.DMin(expression: str, tablename: str, [criteria: str]): any
db.DMax(expression: str, tablename: str, [criteria: str]): any
db.DSum(expression: str, tablename: str, [criteria: str]): any
expression: израз на SQL, в който имената на полета са оградени с квадратни скоби.
tablename: име на таблица (без квадратни скоби).
criteria: клауза WHERE без ключовата дума WHERE, в която имената на полета са оградени с квадратни скоби.
В долния пример се приема, че файлът Employees.odb съдържа таблица с име EmployeeData.
      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
      Dim myDB as Variant
      Set myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
      ' Преброява служителите в таблицата.
      MsgBox myDB.DCount("[ID]", "EmployeeData")
      ' Връща сумата на всички заплати в таблицата.
      MsgBox myDB.DSum("[Salary]", "EmployeeData")
      ' Следват няколко примера за филтриране на таблици.
      MsgBox myDB.DCount("[ID]", "EmployeeData", "[Position] = 'Manager'")
      MsgBox myDB.DCount("[ID]", "EmployeeData", "[Position] = 'Sales' AND [City] = 'Chicago'")
      MsgBox myDB.DCount("[ID]", "EmployeeData", "[FirstName] LIKE 'Paul%'")
    
      myDB = CreateScriptService("Database", "/home/user/Databases/Employees.odb")
      bas = CreateScriptService("Basic")
      bas.MsgBox(myDB.DCount("[ID]", "EmployeeData"))
      bas.MsgBox(myDB.DSum("[Salary]", "EmployeeData"))
      bas.MsgBox(myDB.DCount("[ID]", "EmployeeData", "[Position] = 'Manager'"))
      bas.MsgBox(myDB.DCount("[ID]", "EmployeeData", "[Position] = 'Sales' AND [City] = 'Chicago'"))
      bas.MsgBox(myDB.DCount("[ID]", "EmployeeData", "[FirstName] LIKE 'Paul%'"))
    Изчислява израз на SQL върху единичен запис, върнат от клауза WHERE, която е дефинирана в параметъра Criteria.
Ако заявката върне няколко записа, се взема само първият от тях. Използвайте параметъра OrderClause, за да определите как се сортират резултатите от заявката.
db.DLookup(expression: str, tablename: str, [criteria:str], [orderclause: str]): any
expression: израз на SQL, в който имената на полета са оградени с квадратни скоби.
tablename: име на таблица (без квадратни скоби).
criteria: клауза WHERE без ключовата дума WHERE, в която имената на полета са оградени с квадратни скоби.
orderclause: клауза ORDER BY без ключовите думи ORDER BY. Имената на полета трябва да бъдат оградени с квадратни скоби.
      MsgBox myDB.DLookup("[FirstName]", "EmployeeData", Criteria := "[LastName] LIKE 'Smith'", OrderClause := "[FirstName] DESC")
      MsgBox myDB.DLookup("[Salary]", "EmployeeData", Criteria := "[ID] = '3'")
      MsgBox myDB.DLookup("[Quantity] * [Value]", "Sales", Criteria := "[SaleID] = '5014'")
    
      bas = CreateScriptService("Basic")
      bas.MsgBox(myDB.DLookup("[FirstName]", "EmployeeData", criteria = "[LastName] LIKE 'Smith'", orderclause = "[FirstName] DESC"))
      bas.MsgBox(myDB.DLookup("[Salary]", "EmployeeData", criteria = "[ID] = '3'"))
      bas.MsgBox(myDB.DLookup("[Quantity] * [Value]", "Sales", criteria = "[SaleID] = '5014'"))
    Съхранява съдържанието на таблица или резултатите от заявка SELECT или оператор на SQL в двуизмерен масив. Първият индекс на масива съответства на редовете, а вторият представя колоните.
Може да бъде зададена горна граница за броя върнати записи. По желание имената на колоните могат да бъдат вмъкнати в първия ред на масива.
Резултатният масив ще бъде празен, ако не са върнати редове и не се изискват заглавия на колони.
db.GetRows(sqlcommand: str, directsql: bool = False, header: bool = False, maxrows: int = 0): any
sqlcommand: име на таблица или заявка (без квадратни скоби) или оператор SELECT на SQL.
directsql: когато е True, командата на SQL се изпраща към СУБД без предварителен анализ. Подразбира се False. Аргументът се игнорира за таблици. За заявки прилаганата настройка е тази, която е била зададена при създаване на заявката.
header: когато е True, първият ред на върнатия масив съдържа заглавията на колоните.
maxrows: максималният брой върнати редове. Подразбира се нула, което означава, че няма ограничение за броя връщани редове.
Следват няколко примера за употребата на метода GetRows:
      Dim queryResults as Variant
      ' Връща всички редове в таблицата и заглавията на колоните.
      queryResults = myDB.GetRows("EmployeeData", Header := True)
      ' Връща първите 50 записа за служители, подредени по полето FirstName.
      queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", MaxRows := 50)
    
      queryResults = myDB.GetRows("EmployeeData", header = True)
      queryResults = myDB.GetRows("SELECT * FROM EmployeeData ORDER BY [FirstName]", maxrows = 50)
    Отваря зададения документ с формуляри в нормален режим. Този метод връща екземпляр на услугата FormDocument, съответстващ на указания формулярен документ.
Ако формулярният документ вече е отворен, прозорецът му се активира.
Ако указаният документ с формуляри не съществува, се връща стойността Nothing.
svc.OpenFormDocument(formdocument: str): svc
formdocument: името на обекта FormDocument, който да бъде отворен, като чувствителен към регистъра низ.
Повечето документи с формуляри се съхраняват в корена на документа на Base и могат да бъдат отворени просто чрез имената си както в долния пример:
    Dim oFormDoc As Object
    oFormDoc = myDB.OpenFormDocument("myFormDocument")
  Ако документите с формуляри са организирани в папки, за задаване на отваряния формулярен документ е необходимо да се включи името на папката, както е показано в следващия пример:
    oFormDoc = myDB.OpenFormDocument("myFolder/myFormDocument")
  
    formDoc = myDB.OpenFormDocument("myFormDocument")
  
    formDoc = myDB.OpenFormDocument("myFolder/myFormDocument")
  Отваря прозореца „Изглед с данни“ на указаната заявка и връща екземпляр на услугата Datasheet.
Ако заявката не може да бъде отворена, се връща Nothing.
db.OpenQuery(queryname: str): obj
queryname: името на съществуваща заявка като низ, малките и главните букви се различават.
      myDatabase.OpenQuery("MyQuery")
    
      myDatabase.OpenQuery("MyQuery")
    Изпълнява команда SELECT на SQL, отваря прозорец „Изглед с данни“ с резултатите и връща екземпляр на услугата Datasheet.
db.OpenSql(sql: str, directsql: bool): obj
sql: низ, съдържащ валиден оператор SELECT на SQL. Идентификаторите може да бъдат оградени с квадратни скоби.
directsql: когато е True, командата на SQL се изпраща към системата за управление на бази от данни без предварителен анализ (подразбира се False).
      myDatabase.OpenSql("SELECT * FROM [Customers] ORDER BY [CITY]")
    
      myDatabase.OpenSql("SELECT * FROM [Customers] ORDER BY [CITY]")
    Отваря прозореца „Изглед с данни“ на указаната таблица и връща екземпляр на услугата Datasheet.
db.OpenTable(tablename: str): obj
tablename: името на съществуваща таблица като низ, малките и главните букви се различават.
      myDatabase.OpenTable("MyTable")
    
      myDatabase.OpenTable("MyTable")
    Отхвърля всички промени, нанесени в базата от данни след последното извикване на Commit или Rollback.
db.Rollback()
      myDB.SetTransactionMode(1)
      myDB.RunSql("UPDATE ...")
      ' ...
      If bSomeCondition Then
          myDB.Rollback()
      End If
    
      myDB.SetTransactionMode(1)
      myDB.RunSql("UPDATE ...")
      # ...
      if bSomeCondition:
          myDB.Rollback()
    Изпълнява заявка за действие от оператор на SQL, например създаване на таблица, както и вмъкване, променяне или изтриване на записи.
Методът връща True при успех.
Методът RunSql се отказва със съобщение за грешка, ако базата от данни е била отворена в режим само за четене.
db.RunSql(sqlcommand: str, directsql: bool = False): bool
sqlcommand: име на заявка (без квадратни скоби) или оператор на SQL.
directsql: когато е True, командата на SQL се изпраща към СУБД без предварителен анализ. Подразбира се False. За заявки прилаганата настройка е тази, която е била зададена при създаване на заявката.
      myDatabase.RunSql("INSERT INTO [EmployeeData] VALUES(25, 'Smith', 'John')", DirectSQL := True)
    
      myDatabase.RunSql("INSERT INTO [EmployeeData] VALUES(25, 'Smith', 'John')", directsql = True)
    Определя нивото на изолация на трансакциите в базата от данни.
По подразбиране базите от данни извършват трансакциите в режим на автоматично фиксиране, което означава, че автоматично се изпълнява команда Commit след всеки оператор на SQL.
Използвайте този метод, за да зададете ръчно нивото на изолация на трансакциите. Когато е зададен режим на трансакциите, различен от NONE, скриптът трябва изрично да извика метода Commit, за да приложи промените върху базата от данни.
Този метод връща True при успешно изпълнение.
При смяна на режима на трансакциите се затварят всички екземпляри на Dataset, създадени от текущата база от данни.
db.SetTransactionMode(transactionmode: int = 0): bool
transactionmode: указва режима на трансакциите. Този аргумент трябва да бъде една от константите, дефинирани в com.sun.star.sdbc.TransactionIsolation (подразбира се NONE).
Прочетете раздела Обработка на трансакции по-горе, за да научите повече за използваните в LibreOffice нива на изолация на трансакциите.
      myDB.SetTransactionMode(com.sun.star.sdbc.TransactionIsolation.REPEATABLE_READ)
      oDataset = myDB.CreateDataset("SELECT ...")
      ' ...
      ' Връща се подразбираният режим на трансакциите.
      myDB.SetTransactionMode()
    
      from com.sun.star.sdbc import TransactionIsolation
      myDB.SetTransactionMode(TransactionIsolation.REPEATABLE_READ)
      dataset = myDB.CreateDataset("SELECT ...")
      # ...
      myDB.SetTransactionMode()