From ae5e2b39ca7822547eb8c0c3c98ff8518b2a114f Mon Sep 17 00:00:00 2001 From: dantleech Date: Wed, 8 Oct 2014 08:59:11 +0200 Subject: [PATCH 1/2] Added dedicated querying chapter --- phpcr-shell/index.rst | 1 + phpcr-shell/interacting.rst | 39 --------- phpcr-shell/querying.rst | 164 ++++++++++++++++++++++++++++++++++++ 3 files changed, 165 insertions(+), 39 deletions(-) create mode 100644 phpcr-shell/querying.rst diff --git a/phpcr-shell/index.rst b/phpcr-shell/index.rst index 3b8df7d..7592367 100644 --- a/phpcr-shell/index.rst +++ b/phpcr-shell/index.rst @@ -7,5 +7,6 @@ PHPCR-Shell installation connecting interacting + querying configuration reference diff --git a/phpcr-shell/interacting.rst b/phpcr-shell/interacting.rst index 2a7cf49..8f347b2 100644 --- a/phpcr-shell/interacting.rst +++ b/phpcr-shell/interacting.rst @@ -143,42 +143,3 @@ of :ref:`phpcr_shell_command_nodecopy` which is a workspace command). To persist changes to the repository you must call :ref:`phpcr_shell_command_sessionsave` (or ``save``). You can also refresh (or reset) the session by calling :ref:`phpcr_shell_command_sessionrefresh` (or ``refresh``). - -Queries -------- - -PHPCRSH supports the JCR-SQL2 query language: - -.. code-block:: bash - - PHPCRSH > SELECT title FROM slinpTest:article - +--------------------------------------------+-----------------------------+ - | Path | slinpTest:article.title | - +--------------------------------------------+-----------------------------+ - | /slinp/web/root | Slinp Web Content Framework | - | /slinp/web/root/home | Home | - | /slinp/web/root/articles/Faster-than-light | Faster than light | - +--------------------------------------------+-----------------------------+ - 3 rows in set (0.01 sec) - PHPCRSH > SELECT title FROM slinpTest:article WHERE title="Home" - +----------------------+-------------------------+ - | Path | slinpTest:article.title | - +----------------------+-------------------------+ - | /slinp/web/root/home | Home | - +----------------------+-------------------------+ - 1 rows in set (0.04 sec) - -For more information on JCR-SQL2 refer to the articles on the -`official PHPCR website `_. - -In addition to SELECT PHPCR Shell supports non-standard UPDATE and DELETE queries: - -.. code-block:: bash - - PHPCRSH > DELETE FROM [slinpTest:article] WHERE title="Home" - 1 row(s) affected in 0.01s - -.. code-block:: bash - - PHPCRSH > UPDATE [slinpTest:article] SET title="Away" WHERE title="Home" - 1 row(s) affected in 0.01s diff --git a/phpcr-shell/querying.rst b/phpcr-shell/querying.rst new file mode 100644 index 0000000..9f40ec3 --- /dev/null +++ b/phpcr-shell/querying.rst @@ -0,0 +1,164 @@ +Querying +======== + +Selecting +--------- + +PHPCRSH currently supports the JCR-SQL2 query language when supported by the +implementation (currently all implementations support this language). + +.. code-block:: bash + + PHPCRSH > SELECT title FROM slinpTest:article + +--------------------------------------------+-----------------------------+ + | Path | slinpTest:article.title | + +--------------------------------------------+-----------------------------+ + | /slinp/web/root | Slinp Web Content Framework | + | /slinp/web/root/home | Home | + | /slinp/web/root/articles/Faster-than-light | Faster than light | + +--------------------------------------------+-----------------------------+ + 3 rows in set (0.01 sec) + + PHPCRSH > SELECT title FROM slinpTest:article WHERE title="Home" + +----------------------+-------------------------+ + | Path | slinpTest:article.title | + +----------------------+-------------------------+ + | /slinp/web/root/home | Home | + +----------------------+-------------------------+ + 1 rows in set (0.04 sec) + +The JCR-SQL2 lanugage supports joins, column selection and a range of +operands (e.g. lowercase, uppercase, length, etc). + +For more information on JCR-SQL2 refer to the articles on the +`official PHPCR website `_. + +Update and Delete +----------------- + +In addition to standard support for SELECT queries, PHPCRSH additionally +supports UPDATE and DELETE queries, these query grammers **are not standard** +and are specific to PHPCRSH. + +.. note:: + + UPDATE and DELETE operations are *experimental*. You are advised to test + any updates before hand in a development environment and ensure that you + have a backup. We can take no responsibility for lost data! + +Updating +-------- + +The UPDATE Grammer extends the SELECT grammer: + +.. code-block:: bash + + PHPCRSH > UPDATE [slinpTest:article] SET title="Away" WHERE title="Home" + 1 row(s) affected in 0.01s + + PHPCRSH > UPDATE [slinpTest:article] AS a LEFT JOIN [slinpTest:foobar] AS b ON a.uuid = b.content SET a.title="Away", b.title="Home" WHERE a.title="Home" + 1 row(s) affected in 0.01s + +Multivalue indexes +~~~~~~~~~~~~~~~~~~ + +You can update (or remove) specific multivalue indexes: + +.. code-block:: bash + + PHPCRSH > UPDATE [slinpTest:article] SET title[1] = "Away" WHERE title="Home" + 1 row(s) affected in 0.01s + +The above query will set the multivalue value at index 1 to "Away" when the +value "Home" matches *one of* the multivalue property values. + +.. code-block:: bash + + PHPCRSH > UPDATE [slinpTest:article] SET title[1] = NULL WHERE title="Home" + 1 row(s) affected in 0.01s + +Same as above but the value at index 1 will be removed. + +.. code-block:: bash + + PHPCRSH > UPDATE [slinpTest:article] SET title[] = "Barfoo" WHERE title="Home" + 1 row(s) affected in 0.01s + +The above will *add* the value "barfoo" to the multivalue properties (see also :ref:`phpcr_shell_query_function_arrayappend`) + +See also: :ref:`phpcr_shell_query_function_arrayremove`, :ref:`phpcr_shell_query_function_arrayreplace`, :ref:`phpcr_shell_query_function_arrayappend`, + +Functions +~~~~~~~~~ + +The ``UPDATE`` grammer also allows the use of functions (note that only UPDATE +supports functions). + +.. _phpcr_shell_query_function_arrayremove: + +array_remove +"""""""""""" + +Remove the multivalue property value matching the given value. + +Usage: + +.. code-block:: bash + + PHPCRSH> UPDATE [nt:unstructured] AS a SET a.tags = array_remove(a.tags, 'Planes') WHERE a.tags = 'Planes' + +Arguments: + +- **propertyName**: Property name (including selector) of the multivalue + property +- **value**: Value to match and remove + +.. _phpcr_shell_query_function_arrayreplace: + +array_replace +""""""""""""" + +Replace a given multivalue property value. + +Usage: + +.. code-block:: bash + + PHPCRSH> UPDATE [nt:unstructured] SET tags = array_replace(tags, 'Planes', 'Rockets') WHERE tags = 'Planes' + +Arguments: + +- **propertyName**: Property name (including selector) of the multivalue + property +- **value**: Value to replace +- **replacement**: Replacement value + +.. _phpcr_shell_query_function_arrayappend: + +array_append +"""""""""""" + +Append a value to a multivalue property. + +Usage: + +.. code-block:: bash + + PHPCRSH> UPDATE [nt:unstructured] SET tags - array_append(tags, 'Planes') WHERE tags = 'Planes' + +Arguments: + +- **propertyName**: Property name (including selector) of the multivalue + property +- **value**: Value to append + +Deleting +-------- + +Delete is as you might expect, and is essentially gramatically identical to ``SELECT`` but +without the column selection: + +.. code-block:: bash + + PHPCRSH > DELETE FROM [slinpTest:article] WHERE title="Home" + 1 row(s) affected in 0.01s From 3008cce49fd8aa950542613ee8a9660cb73776e7 Mon Sep 17 00:00:00 2001 From: dantleech Date: Sat, 25 Oct 2014 09:35:17 +0200 Subject: [PATCH 2/2] Updated --- phpcr-shell/querying.rst | 79 +++++++++++++++++++++++----------------- 1 file changed, 46 insertions(+), 33 deletions(-) diff --git a/phpcr-shell/querying.rst b/phpcr-shell/querying.rst index 9f40ec3..56c9d03 100644 --- a/phpcr-shell/querying.rst +++ b/phpcr-shell/querying.rst @@ -59,35 +59,6 @@ The UPDATE Grammer extends the SELECT grammer: PHPCRSH > UPDATE [slinpTest:article] AS a LEFT JOIN [slinpTest:foobar] AS b ON a.uuid = b.content SET a.title="Away", b.title="Home" WHERE a.title="Home" 1 row(s) affected in 0.01s -Multivalue indexes -~~~~~~~~~~~~~~~~~~ - -You can update (or remove) specific multivalue indexes: - -.. code-block:: bash - - PHPCRSH > UPDATE [slinpTest:article] SET title[1] = "Away" WHERE title="Home" - 1 row(s) affected in 0.01s - -The above query will set the multivalue value at index 1 to "Away" when the -value "Home" matches *one of* the multivalue property values. - -.. code-block:: bash - - PHPCRSH > UPDATE [slinpTest:article] SET title[1] = NULL WHERE title="Home" - 1 row(s) affected in 0.01s - -Same as above but the value at index 1 will be removed. - -.. code-block:: bash - - PHPCRSH > UPDATE [slinpTest:article] SET title[] = "Barfoo" WHERE title="Home" - 1 row(s) affected in 0.01s - -The above will *add* the value "barfoo" to the multivalue properties (see also :ref:`phpcr_shell_query_function_arrayappend`) - -See also: :ref:`phpcr_shell_query_function_arrayremove`, :ref:`phpcr_shell_query_function_arrayreplace`, :ref:`phpcr_shell_query_function_arrayappend`, - Functions ~~~~~~~~~ @@ -113,26 +84,68 @@ Arguments: property - **value**: Value to match and remove +.. _phpcr_shell_query_function_array: + +array +""""" + +Provides an array value, analagous to the ``array`` keyword in PHP: + +.. code-block:: bash + + PHPCRSH> UPDATE [nt:unstructured] SET tags = array('One', 'Two', 'Three') + +Arguments: + +- List of values + .. _phpcr_shell_query_function_arrayreplace: array_replace """"""""""""" -Replace a given multivalue property value. +Replace a given multivalue property value, or remove it by setting it to +``NULL``. -Usage: +Replace a value: .. code-block:: bash - PHPCRSH> UPDATE [nt:unstructured] SET tags = array_replace(tags, 'Planes', 'Rockets') WHERE tags = 'Planes' + PHPCRSH> UPDATE [nt:unstructured] SET tags = array_replace(tags, 'Planes', 'Rockets') + +Remove matching values: + +.. code-block:: bash + + PHPCRSH> UPDATE [nt:unstructured] SET tags = array_replace(tags, 'Planes', NULL) Arguments: - **propertyName**: Property name (including selector) of the multivalue property -- **value**: Value to replace +- **value**: Value to replace, use ``NULL`` to remove a value - **replacement**: Replacement value +.. _phpcr_shell_query_function_arrayreplaceat: + +array_replace_at +"""""""""""""""" + +Replace a given multivalue property value at the specified index. + +Usage: + +.. code-block:: bash + + PHPCRSH> UPDATE [nt:unstructured] SET tags = array_replace_at(tags, 0, 'Rockets') WHERE tags = 'Planes' + +Arguments: + +- **propertyName**: Property name (including selector) of the multivalue + property +- **index**: Index at which the new value should be set +- **value**: Value to set + .. _phpcr_shell_query_function_arrayappend: array_append