How do I create a collection in Basex from a client?
Tuesday, 14 July 2026 · 10 messages · last reply 16 Jul 2026
BE
Ben Engbers14 Jul 2026 18:30 #
Hi
Following a comment on Mistral.ai, I’ve made some changes to my C++ library. The biggest change concerns how the results of called methods are processed. In the previous version, I used one large static class to store the results. Now, the results of each call are stored in their own instance of the ResultsObject class.
The library has been largely rewritten. The errors I’m still encountering stem more from my limited knowledge of XQuery than from errors in the library.
According to Mistral, I can create a collection in a new database as follows:
std::string TestDB = “TestClient”
Session.Create(TestDB); // Creates a database
Session.Add(TestDB + “/Files/”, “”); // Creates a collection.
According to the client protocol, these are the arguments for the Add command: \09 {path} {input}.
When {input} is empty, I cannot construct a valid message for the server; the server continues to wait for a terminating character.
My question is: which client commands should I use to successfully create an (empty) collection?
Ben
CG
Christian Grün14 Jul 2026 18:50 #
Hi Ben,
Quoted text · Ben Engbers · 1 line
> My question is: which client commands should I use to successfully
create an (empty) collection?
A collection results from the paths of the stored documents. There is both no need and no way to create explicit collection directories.
Hope this helps,
Christian
BE
Ben Engbers14 Jul 2026 21:34 #
Okay,
This command successfully adds a document to the open database: Session.Add(“Files/Downloads/Download_1”,
“https://raw.githubusercontent.com/BaseXdb/basex/master/basex-api/src/test/resources/first.xml”);
I’ll now figure out how to modify the following loop so that the XML
documents from the directory are added to the “Files/System/<name>”
collection. Once I’ve figured that out, I’ll share the relevant code.
for (const auto &entry : filesystem::directory_iterator(path)) {
const std::string name =
entry.path().filename().string();
if (entry.path().extension() == “.xml”) {
cout << entry.path();
db_Result_1 = Session.Add(“Add_XML_3”, entry.path());
cout << db_Result_1->getInfoString() <<
endl;
++count;
}
};Quoted text · Christian Grün · 10 lines
Op 14-07-2026 om 18:50 schreef Christian Grün: > Hi Ben, > >> My question is: which client commands should I use to successfully > create an (empty) collection? > > A collection results from the paths of the stored documents. There is both no need and no way to create explicit collection directories. > > Hope this helps, > Christian
BE
Ben Engbers15 Jul 2026 18:11 #
I ended with this code which store 4 documents in a database:
for (const auto &entry : filesystem::directory_iterator(path)) {
const std::string name = entry.path().filename().string();
if (entry.path().extension() == ".xml" {
cout << entry.path() << endl;
std::ifstream file(entry.path());
std::string xmlContent((std::istreambuf_iterator<char>(file)),
std::istreambuf_iterator<char>());
std::string id = extractID(Session, xmlContent, TestDB);
Session.Add("/Files/System/" + id + ".xml", xmlContent);
++count;
}
};
In the BasexGUI I see 4 separate objects "Files/System/<ID 1 to 4>.xml"Is this a collection or are they 4 separate documents?
Ben
Quoted text · Ben Engbers · 13 lines
Op 14-07-2026 om 21:34 schreef Ben Engbers via BaseX-Talk: > Op 14-07-2026 om 18:50 schreef Christian Grün: >> Hi Ben, >> >>> My question is: which client commands should I use to successfully >> create an (empty) collection? >> >> A collection results from the paths of the stored documents. There is >> both no need and no way to create explicit collection directories. >> >> Hope this helps, >> Christian >
CG
Christian Grün15 Jul 2026 18:24 #
Hi Ben,
I agree with Mistral:
• /Files/System/ is a collection (directory).
• <ID 1 to 4>.xml are 4 separate documents stored inside that collection.
If you wanted to store them as a single collection (e.g., merging all XML files into one document), you would need to combine their contents and add them under a single path. But your current approach treats them as distinct documents.
Cheers,
Christian
Quoted text · Ben Engbers · 33 lines
Von: Ben Engbers <Ben.Engbers at Be-Logical.nl> Gesendet: Mittwoch, 15. Juli 2026 18:11 An: Christian Grün; Basex Mail-lijst Betreff: Re: [basex-talk] Re: How do I create a collection in Basex from a client? I ended with this code which store 4 documents in a database: for (const auto &entry : filesystem::directory_iterator(path)) { const std::string name = entry.path().filename().string(); if (entry.path().extension() == ".xml" { cout << entry.path() << endl; std::ifstream file(entry.path()); std::string xmlContent((std::istreambuf_iterator<char>(file)), std::istreambuf_iterator<char>()); std::string id = extractID(Session, xmlContent, TestDB); Session.Add("/Files/System/" + id + ".xml", xmlContent); ++count; } }; In the BasexGUI I see 4 separate objects "Files/System/<ID 1 to 4>.xml" Is this a collection or are they 4 separate documents? Ben Op 14-07-2026 om 21:34 schreef Ben Engbers via BaseX-Talk: > Op 14-07-2026 om 18:50 schreef Christian Grün: >> Hi Ben, >> >>> My question is: which client commands should I use to successfully >> create an (empty) collection? >> >> A collection results from the paths of the stored documents. There is >> both no need and no way to create explicit collection directories. >> >> Hope this helps, >> Christian >
BE
Ben Engbers15 Jul 2026 19:58 #
A general question; what are the advantages of using a collection versus using different documents (within a collection)? I guess that the syntax for building query's might be different, but else?...
Ben
Quoted text · Christian Grün · 13 lines
Op 15-07-2026 om 18:24 schreef Christian Grün: > Hi Ben, > > I agree with Mistral: > > • /Files/System/ is a collection (directory). > • <ID 1 to 4>.xml are 4 separate documents stored inside that collection. > > If you wanted to store them as a single collection (e.g., merging all XML files into one document), you would need to combine their contents and add them under a single path. But your current approach treats them as distinct documents. > > Cheers, > Christian > ________________________________________
--
Ben Engbers
Grietjeshof 77
6721 VH Bennekom
+31 6 23634840
CG
Christian Grün15 Jul 2026 20:12 #
There is no entity in BaseX that would call a collection. Collections result implicitly from the documents you store. See [1] for more details.
[1] https://docs.basex.org/main/Databases
Quoted text · Ben Engbers · 26 lines
Von: Ben Engbers <Ben.Engbers at Be-Logical.nl> Gesendet: Mittwoch, 15. Juli 2026 19:58 An: Christian Grün; Basex Mail-lijst Betreff: Re: AW: [basex-talk] Re: How do I create a collection in Basex from a client? A general question; what are the advantages of using a collection versus using different documents (within a collection)? I guess that the syntax for building query's might be different, but else?... Ben Op 15-07-2026 om 18:24 schreef Christian Grün: > Hi Ben, > > I agree with Mistral: > > • /Files/System/ is a collection (directory). > • <ID 1 to 4>.xml are 4 separate documents stored inside that collection. > > If you wanted to store them as a single collection (e.g., merging all XML files into one document), you would need to combine their contents and add them under a single path. But your current approach treats them as distinct documents. > > Cheers, > Christian > ________________________________________ -- Ben Engbers Grietjeshof 77 6721 VH Bennekom +31 6 23634840
GS
`fn:collection`(
`$source` `as ```xs:string?``` := ``()`
)` as ```item()*generally, a collection is going to be a sequence of document nodes (~sequence of XML documents) but it doesn't have to be.
What do you expect a collection to be? It sounds like you've got something in mind but I don't recognize it.``
Quoted text · Ben Engbers · 27 lines
On Wed, Jul 15, 2026, at 13:58, Ben Engbers via BaseX-Talk wrote: > A general question; what are the advantages of using a collection versus > using different documents (within a collection)? I guess that the syntax > for building query's might be different, but else?... > > Ben > > Op 15-07-2026 om 18:24 schreef Christian Grün: > > Hi Ben, > > > > I agree with Mistral: > > > > • /Files/System/ is a collection (directory). > > • <ID 1 to 4>.xml are 4 separate documents stored inside that collection. > > > > If you wanted to store them as a single collection (e.g., merging all XML files into one document), you would need to combine their contents and add them under a single path. But your current approach treats them as distinct documents. > > > > Cheers, > > Christian > > ________________________________________ > -- > Ben Engbers > Grietjeshof 77 > 6721 VH Bennekom > +31 6 23634840 > >
BE
Ben Engbers15 Jul 2026 21:55 #
I had in mind that a collection in BasexGUI would be displayed as a hierarchy with the collection’s name at the top and XML files (with their names) listed below it.
What I see is a path with a name at the top for each file (for example, Files/System/<name_1>), followed by the XML document itself. The pattern Files/System/<name_#> is repeated for each new document.
In BasexGUI, I personally still find it difficult to conceptually distinguish between a document and a collection.
Ben
Quoted text · Graydon Saunders · 15 lines
Op 15-07-2026 om 20:15 schreef Graydon Saunders: > https://qt4cg.org/specifications/xpath-functions-40/Overview.html#func- > collection <https://qt4cg.org/specifications/xpath-functions-40/ > Overview.html#func-collection> says > > |fn:collection|( > |$source| |as |||xs:string?|||:= ||()| > )| as |||item()* > > generally, a collection is going to be a sequence of document nodes > (~sequence of XML documents) but it doesn't have to be. > > What do you expect a collection to be? It sounds like you've got > something in mind but I don't recognize it.|| >
GS
Graydon Saunders16 Jul 2026 16:12 #
Quoted text · Ben Engbers · 1 line
> *In BasexGUI, I personally still find it difficult to conceptually distinguish between a document and a collection.*
Broadly speaking, an XPath collection/the result of the collection() function is what you might do to manipulate a group of documents when you don't have a database. (I presume this is why Saxon's implementation of the collection function is so extensive; for a long time, if you wanted to use XSLT to manipulate some variable number of documents, that's how you would do it.)
I think what you're describing as a collection is something that in BaseX makes much more sense to approach as a database.
XML documents don't retain a concept of files or a concept of a file system; the individual documents have a document-uri property, and the path component of the document-uri can be (but doesn't have to be) derived from the document's original file system path, but after the document has been loaded by collection() or
db:create() or something else, a connection back to the file system isn't there. document-uri as a document property is specific to the document; there isn't a larger thing for it to be derived from.
I don't think there's a way to associate a base-uri() with a collection, which is what "the collection has a path component, the documents have a document-uri that's only a single path component" sounds like. But base-uri is deep magic and someone may pop up and explain that you can do that.Quoted text · Ben Engbers · 28 lines
On Wed, Jul 15, 2026, at 15:55, Ben Engbers wrote: > I had in mind that a collection in BasexGUI would be displayed as a > hierarchy with the collection’s name at the top and XML files (with > their names) listed below it. > What I see is a path with a name at the top for each file (for example, > Files/System/<name_1>), followed by the XML document itself. The pattern > Files/System/<name_#> is repeated for each new document. > In BasexGUI, I personally still find it difficult to conceptually > distinguish between a document and a collection. > > Ben > > Op 15-07-2026 om 20:15 schreef Graydon Saunders: > > https://qt4cg.org/specifications/xpath-functions-40/Overview.html#func- > > collection <https://qt4cg.org/specifications/xpath-functions-40/ > > Overview.html#func-collection> says > > > > |fn:collection|( > > |$source| |as |||xs:string?|||:= ||()| > > )| as |||item()* > > > > generally, a collection is going to be a sequence of document nodes > > (~sequence of XML documents) but it doesn't have to be. > > > > What do you expect a collection to be? It sounds like you've got > > something in mind but I don't recognize it.|| > > >
Written for BaseX 12.4. BaseX may have changed since: please check the current documentation.
⚡Generated with XQuery