Documentation

> CREATE DB users

> ADD <record>hello</record>

On Sat, 2013-08-24 at 16:25 +0100, Thomas Daly wrote: > Hello, > > Thank you for this system, which looks promising. > > I would like to request better documentation to show how to do the > most basic things. I am trying to create a new database and add a > single new record to it. I don't want to start with a pre-written > XML document. So using the command line client tool: > > > CREATE DB users > Database 'users' created in 214.89 ms. > > Then I refer to the ADD command > http://docs.basex.org/wiki/Commands#ADD which suggests an XML string > can be added. So I try: > > > ADD <record>hello</record> > Name '' is invalid. > > All the examples of ADD involve adding existing XML files. A path to > the database is referred to, but having just created the database I > have no idea what the path is.

> CREATE DB db1

> INFO STORAGE

> ADD mydoc.xml

> INFO STORAGE

> ADD TO doc2.xml <a/>

> INFO STORAGE

> CREATE DB db2 mydoc.xml

> INFO STORAGE

> CREATE DB db3 <a/>

> INFO STORAGE

> Referring to tutorials and slides on page > http://docs.basex.org/wiki/Getting_Started, the link to XMLPrague > 2013 is broken.

> BaseX adventures starts at an advanced level of querying a host of XML files. W3Schools XQuery seems all about > querying existing databases

> I can't find anything on how to add or update a single record.

> I'm sure with enough trial and error I'll work out how to do it. My > point is that I feel it ought to be more obvious how to carry out the > most basic CRUD operations.

> CREATE DB db1

> ADD mydoc.xml

> ADD TO doc2.xml <a/>

> INFO STORAGE

> XQUERY insert node <newnode/> into <a/>

> XQUERY insert node <newnode/> into doc('doc2.xml')/a

At 11:00 25/08/2013, you wrote: >Send BaseX-Talk mailing list submissions to > basex-talk at mailman.uni-konstanz.de > >To subscribe or unsubscribe via the World Wide Web, visit > https://mailman.uni-konstanz.de/mailman/listinfo/basex-talk >or, via email, send a message with subject or body 'help' to > basex-talk-request at mailman.uni-konstanz.de > >You can reach the person managing the list at > basex-talk-owner at mailman.uni-konstanz.de > >When replying, please edit your Subject line so it is more specific >than "Re: Contents of BaseX-Talk digest..." > > >Today's Topics: > > 1. Documentation (Thomas Daly) > 2. Re: Documentation (Dimitar Popov) > > >---------------------------------------------------------------------- > >Message: 1 >Date: Sat, 24 Aug 2013 16:25:17 +0100 >From: Thomas Daly <thomas.daly at live.com> >To: basex-talk at mailman.uni-konstanz.de >Subject: [basex-talk] Documentation >Message-ID: <BLU0-SMTP12145626E8EAB6750E955A2914F0 at phx.gbl> >Content-Type: text/plain; charset="us-ascii"; format=flowed > >Hello, > >Thank you for this system, which looks promising. > >I would like to request better documentation to show how to do the >most basic things. I am trying to create a new database and add a >single new record to it. I don't want to start with a pre-written >XML document. So using the command line client tool: > > > CREATE DB users >Database 'users' created in 214.89 ms. > >Then I refer to the ADD command >http://docs.basex.org/wiki/Commands#ADD which suggests an XML string >can be added. So I try: > > > ADD <record>hello</record> >Name '' is invalid. > >All the examples of ADD involve adding existing XML files. A path to >the database is referred to, but having just created the database I >have no idea what the path is. > >Referring to tutorials and slides on page >http://docs.basex.org/wiki/Getting_Started, the link to XMLPrague >2013 is broken. BaseX adventures starts at an advanced level of >querying a host of XML files. W3Schools XQuery seems all about >querying existing databases, I can't find anything on how to add or >update a single record. > >I'm sure with enough trial and error I'll work out how to do it. My >point is that I feel it ought to be more obvious how to carry out the >most basic CRUD operations. > >Best regards, >Thomas > > > >------------------------------ > >Message: 2 >Date: Sat, 24 Aug 2013 23:31:36 +0200 >From: Dimitar Popov <dp at basex.org> >To: basex-talk at mailman.uni-konstanz.de >Subject: Re: [basex-talk] Documentation >Message-ID: <1377379896.5833.0.camel@darkrider> >Content-Type: text/plain; charset="UTF-8" > > >On Sat, 2013-08-24 at 16:25 +0100, Thomas Daly wrote: > > Hello, > > > > Thank you for this system, which looks promising. > > > > I would like to request better documentation to show how to do the > > most basic things. I am trying to create a new database and add a > > single new record to it. I don't want to start with a pre-written > > XML document. So using the command line client tool: > > > > > CREATE DB users > > Database 'users' created in 214.89 ms. > > > > Then I refer to the ADD command > > http://docs.basex.org/wiki/Commands#ADD which suggests an XML string > > can be added. So I try: > > > > > ADD <record>hello</record> > > Name '' is invalid. > > > > All the examples of ADD involve adding existing XML files. A path to > > the database is referred to, but having just created the database I > > have no idea what the path is. > >BaseX supports the notion of collections, i.e. one can store multiple >XML documents into a single database. Each non-empty database contains >at least one document. Each stored document must have a name. This is >the reason why when calling the ADD command with an XML fragment one >must specify the name of the new document. However, if a file is >specified as input, then the file name is implicitly used as a name of >the new document. > >Similar behavior has the CREATE DB command. If called with a file, then >a document with the name of the file will be created. If called with an >XML fragment, then the database name will be used as the name of the >first document. The following examples illustrate the two commands: > > > CREATE DB db1 >Database 'db1' created in 68.92 ms. > > > INFO STORAGE >PRE DIS SIZ ATS ID NS KIND CONTENT >----------------------------------------- > > > ADD mydoc.xml >Path "mydoc.xml" added in 15.36 ms. > > > INFO STORAGE >PRE DIS SIZ ATS ID NS KIND CONTENT >------------------------------------------- > 0 1 2 1 0 0 DOC mydoc.xml > 1 1 1 1 1 0 ELEM a > > > ADD TO doc2.xml <a/> >Path "doc2.xml" added in 4.5 ms. > > > INFO STORAGE >PRE DIS SIZ ATS ID NS KIND CONTENT >------------------------------------------- > 0 1 2 1 0 0 DOC mydoc.xml > 1 1 1 1 1 0 ELEM a > 2 3 2 1 2 0 DOC doc2.xml > 3 1 1 1 3 0 ELEM a > > > CREATE DB db2 mydoc.xml >Database 'db2' created in 12.57 ms. > > > INFO STORAGE >PRE DIS SIZ ATS ID NS KIND CONTENT >------------------------------------------- > 0 1 2 1 0 0 DOC mydoc.xml > 1 1 1 1 1 0 ELEM a > > > CREATE DB db3 <a/> >Database 'db3' created in 13.6 ms. > > > INFO STORAGE >PRE DIS SIZ ATS ID NS KIND CONTENT >----------------------------------------- > 0 1 2 1 0 0 DOC db3.xml > 1 1 1 1 1 0 ELEM a > > > > Referring to tutorials and slides on page > > http://docs.basex.org/wiki/Getting_Started, the link to XMLPrague > > 2013 is broken. > >Thanks, I fixed the link. Please, report such inaccuracies or feel free >to edit the wiki yourself. > > > BaseX adventures starts at an advanced level of querying a host > of XML files. W3Schools XQuery seems all about > > querying existing databases > >The BaseX documentation contains only the BaseX specific functionality - >the purpose is not to duplicate the W3C specification or the tutorials >at W3Schools. However, XQuery questions are readily answered on the >mailing list ;) > > > I can't find anything on how to add or update a single record. > >The XQuery Update Facility might be helpful to you [1]. > > > I'm sure with enough trial and error I'll work out how to do it. My > > point is that I feel it ought to be more obvious how to carry out the > > most basic CRUD operations. > >I couldn't agree more. On the other hand the BaseX team gives its best >to maintain the documentation and is always open to improvement >suggestions. So if you have any concrete ideas how the documentation can >be made more useful, they will be most welcome. > >Regards, >Dimitar > >[1] http://www.w3.org/TR/xquery-update-10/ > > > > >------------------------------ > >_______________________________________________ >BaseX-Talk mailing list >BaseX-Talk at mailman.uni-konstanz.de >https://mailman.uni-konstanz.de/mailman/listinfo/basex-talk > > >End of BaseX-Talk Digest, Vol 44, Issue 24 >******************************************

On Sun, 2013-08-25 at 16:42 +0100, Thomas Daly wrote: > Thank you very much for your reply. > > I assume that in your example commands, mydoc.xml already existed as > a file on your hard drive.

> In my case, the system looked for mydoc.xml rather than create it: > > > CREATE DB db1 > Database 'db1' created in 14.41 ms. > > ADD mydoc.xml > Resource "/home/tcd/mydoc.xml" not found.

> Your 2nd ADD command worked, which I assume gives us an XML file > empty apart from a root node <a/>: > > > ADD TO doc2.xml <a/> > Path "doc2.xml" added in 2.72 ms. > > INFO STORAGE > PRE DIS SIZ ATS ID NS KIND CONTENT > ------------------------------------------ > 0 1 2 1 0 0 DOC doc2.xml > 1 1 1 1 1 0 ELEM a > > Now I'd like to add a new node to the new document. I've tried two > variants as follows: > > > XQUERY insert node <newnode/> into <a/> > > Query executed in 2.09 ms.

> XQUERY insert node <newnode/> into /a

> > XQUERY insert node <newnode/> into doc('doc2.xml')/a > Stopped at ., 1/33: > [FODC0002] Resource '/home/tcd/doc2.xml' does not exist.

> XQUERY insert node <newnode/> into doc('db1/doc2.xml')/a > Although the first XQUERY command appeared to work, if I export the > XML file with the EXPORT command and examine it, unfortunately the > new node is not present. The file just contains the <a/> node.

> Is there any variation of the EXPORT command that will simply echo > the contents of the XML file to the terminal, rather than to a > file? If not, that would be a useful addition.

> XQUERY doc('db1/doc2.xml')