Mercurial > libervia-backend

annotate doc/libervia-cli/pubsub_cache.rst @ 3942:a92eef737703

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
plugin XEP-0373: download public keys if they are not found in local storage: public keys were only obtained from PEP notifications, however this wasn't working if the entity was not in our roster. Now if no public key is retrieved from local storage, the public key node is requested, and an error is raised if nothing is found. This allows the use of OX with entities which are not in roster. rel 380
author Goffi <goffi@goffi.org>
date Sat, 15 Oct 2022 20:38:33 +0200
parents d0b66efc6c0e
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3612
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
1 .. _libervia-cli_pubsub_cache:
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
2
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
3 =====================================
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
4 pubsub/cache: PubSub Cache Management
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
5 =====================================
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
6
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
7 Libervia runs transparently a cache for pubsub. That means that according to internal
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
8 criteria, some pubsub items are stored locally.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
9
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
10 The ``cache`` subcommands let user inspect and manipulate the internal cache.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
11
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
12 get
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
13 ===
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
14
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
15 Retrieve items from internal cache only. Most end-users won't need to use this command, as
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
16 the usual ``pubsub get`` command will use cache transparently. However, it may be useful
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
17 to inspect local cache, notably for debugging.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
18
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
19 The parameters are basically the same as for :ref:`li_pubsub_get`.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
20
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
21 example
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
22 -------
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
23
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
24 Retrieve the last 2 cached items for personal blog::
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
25
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
26 $ li pubsub cache get -n urn:xmpp:microblog:0 -M 2
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
27
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
28 .. _li_pubsub_cache_sync:
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
29
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
30 sync
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
31 ====
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
32
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
33 Synchronise or resynchronise a pubsub node. If the node is already in cache, it will be
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
34 deleted then re-cached. Node will be put in cache even if internal policy doesn't request
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
35 a synchronisation for this kind of nodes. Node will be (re-)subscribed to keep cache
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
36 synchronised.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
37
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
38 All items of the node (up to the internal limit which is high), will be retrieved and put
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
39 in cache, even if a previous version of those items have been deleted by the
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
40 :ref:`li_pubsub_cache_purge` command.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
41
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
42
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
43 example
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
44 -------
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
45
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
46 Resynchronise personal blog::
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
47
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
48 $ li pubusb cache sync -n urn:xmpp:microblog:0
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
49
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
50 .. _li_pubsub_cache_purge:
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
51
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
52 purge
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
53 =====
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
54
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
55 Remove items from cache. This may be desirable to save resource, notably disk space.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
56
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
57 Note that once a pubsub node is cached, the cache is the source of trust. That means that
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
58 if cache is not explicitly bypassed when retrieving items of a pubsub node (notably with
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
59 the ``-C, --no-cache`` option of :ref:`li_pubsub_get`), only items found in cache will be
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
60 returned, thus purged items won't be used or returned anymore even if they still exists on
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
61 the original pubsub service.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
62
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
63 If you have purged items by mistake, it is possible to retrieve them either node by node
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
64 using :ref:`li_pubsub_cache_sync`, or by resetting the whole pubsub cache with
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
65 :ref:`li_pubsub_cache_reset`.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
66
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
67 If you have a node or a profile (e.g. a component) caching a lot of items frequently, you
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
68 may use this command using a scheduler like cron_.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
69
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
70 .. _cron: https://en.wikipedia.org/wiki/Cron
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
71
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
72 examples
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
73 --------
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
74
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
75 Remove all blog and event items from cache if they haven't been updated since 6 months::
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
76
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
77 $ li pubsub cache purge -t blog -t event -b "6 months ago"
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
78
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
79 Remove items from profile ``ap_gateway`` if they have been created more that 2 months
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
80 ago::
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
81
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
82 $ li pubsub cache purge -p ap_gateway --created-before "2 months ago"
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
83
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
84 .. _li_pubsub_cache_reset:
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
85
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
86 reset
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
87 =====
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
88
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
89 Reset the whole pubsub cache. This means that all nodes and all them items will be removed
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
90 from cache. After this command, cache will be re-filled progressively as if it where a new
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
91 one.
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
92
3669
23be54db81f1 doc (cli/pubsub_cache): add a warning for `reset`
Goffi <goffi@goffi.org>
parents: 3612
diff changeset
93 .. note::
23be54db81f1 doc (cli/pubsub_cache): add a warning for `reset`
Goffi <goffi@goffi.org>
parents: 3612
diff changeset
94
23be54db81f1 doc (cli/pubsub_cache): add a warning for `reset`
Goffi <goffi@goffi.org>
parents: 3612
diff changeset
95 Use this command with caution: even if cache will be re-constructed with time, that
23be54db81f1 doc (cli/pubsub_cache): add a warning for `reset`
Goffi <goffi@goffi.org>
parents: 3612
diff changeset
96 means that items will have to be retrieved again, that may be resource intensive both
23be54db81f1 doc (cli/pubsub_cache): add a warning for `reset`
Goffi <goffi@goffi.org>
parents: 3612
diff changeset
97 for your machine and for the pubsub services which will be used. That also means that
23be54db81f1 doc (cli/pubsub_cache): add a warning for `reset`
Goffi <goffi@goffi.org>
parents: 3612
diff changeset
98 searching items will return less results until all desired items are cached again.
23be54db81f1 doc (cli/pubsub_cache): add a warning for `reset`
Goffi <goffi@goffi.org>
parents: 3612
diff changeset
99
23be54db81f1 doc (cli/pubsub_cache): add a warning for `reset`
Goffi <goffi@goffi.org>
parents: 3612
diff changeset
100 Also note that all items of cached nodes are retrieved, even if you have previously
23be54db81f1 doc (cli/pubsub_cache): add a warning for `reset`
Goffi <goffi@goffi.org>
parents: 3612
diff changeset
101 purged items, they will be retrieved again.
23be54db81f1 doc (cli/pubsub_cache): add a warning for `reset`
Goffi <goffi@goffi.org>
parents: 3612
diff changeset
102
3612
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
103 example
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
104 -------
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
105
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
106 Reset the whole pubsub cache::
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
107
21e7d46b988c doc (cli/pubsub): document pubsub cache management commands
Goffi <goffi@goffi.org>
parents:
diff changeset
108 $ li pubsub cache reset
3670
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
109
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
110 search
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
111 ======
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
112
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
113 Search items into pubsub cache. The search is done on the whole cache, it's not restricted
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
114 to a single node/profile (even if it may be if suitable filters are specified). Full-Text
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
115 Search can be done with ``-f FTS, --fts FTS`` argument, as well as filtering on parsed
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
116 data (with ``-F PATH OPERATOR VALUE, --field PATH OPERATOR VALUE``, see below).
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
117
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
118 By default, parsed data are returned, with the 3 additional keys ``pubsub_service``,
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
119 ``pubsub_items`` (the search being done on the whole cache, those data are here to get the
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
120 full location of each item) and ``node_profile``.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
121
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
122 "Parsed data" are the result of the parsing of the items XML payload by feature aware
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
123 plugins. Those data are usually more readable and easier to work with. Parsed data are
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
124 only stored when a parser is registered for a specific feature, that means that a Pubsub
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
125 item in cache may not have parsed data at all, in which case an empty dict will be used
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
126 instead (and ``-P, --payload`` argument should be used to get content of the item).
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
127
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
128 The dates are normally stored as `Unix time`_ in database, but the default output convert
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
129 the ``updated``, ``created`` and ``published`` fields to human readable local time. Use
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
130 ``--output simple`` if you want to keep the float (or int) value.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
131
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
132 XML item payload is not returned by default, but it can be added to the ``item_payload``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
133 field if ``-P, --payload`` argument is set. You can also use the ``--output xml`` (or
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
134 ``xml_raw`` if you don't want prettifying) to output directly the highlighted XML
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
135 — without the parsed data —, to have an output similar to the one of ``li pubsub get``.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
136
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
137 If you are interested only in a specific data (e.g. item id and title), the ``-k KEY,
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
138 --key KEY`` can be used.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
139
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
140 You'll probably want to limit result size by using ``-l LIMIT, --limit LIMIT``, and do
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
141 pagination using ``-i INDEX, --index INDEX``.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
142
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
143 .. _Unix time: https://en.wikipedia.org/wiki/Unix_time
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
144
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
145 Filters
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
146 -------
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
147
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
148 By default search returns all items in cache, you have to use filter to specify what you
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
149 are looking after. We can split filters in 3 categories: nodes/items metadata,
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
150 Full-Text Search query and parsed metadata.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
151
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
152 Nodes/items metadata are the generic information you have on a node: which profile it
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
153 belong too, which pubsub service it's coming from, what's the name or type of the node,
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
154 etc.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
155
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
156 Arguments there should be self-explanatory. Type (set with ``-t TYPE, --type TYPE``) and
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
157 subtype (set with ``-S SUBTYPE, --subtype SUBTYPE``) are values dependent of the
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
158 plugin/feature associated with the node, so we can't list them in an exhaustive way here.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
159 The most common type is probably ``blog``, from which a subtype can be ``comment``. An
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
160 empty string can be used to find items with (sub)type not set.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
161
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
162 It's usually a good idea to specify a profile with ``-p PROFILE, --profile PROFILE``,
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
163 otherwise you may get duplicated results.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
164
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
165 Full-Text Search
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
166 ----------------
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
167
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
168 You can specify a Full-Text Search query with the ``-f FTS_QUERY, --fts FTS_QUERY``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
169 argument. The engine is currently SQLite FTS5, and you can check its `query syntax`_.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
170 FTS is done on the whole raw XML payload, that means that all data there can be matched
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
171 (including XML tags and attributes).
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
172
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
173 FTS queries are indexed, that means that they are fast and efficient.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
174
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
175 .. note::
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
176
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
177 Futures version of Libervia will probably include other FTS engines (support for
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
178 PostgreSQL and MySQL/MariaDB is planned). Thus the syntax may vary depending on the
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
179 engine, or a common syntax may be implemented for all engines in the future. Keep that
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
180 in mind if you plan to use FTS capabilities in long-term queries, e.g. in scripts.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
181
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
182 .. _query syntax: https://sqlite.org/fts5.html#full_text_query_syntax
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
183
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
184 Parsed Metadata Filters
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
185 -----------------------
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
186
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
187 It is possible to filter on any field of parsed data. This is done with the ``-F PATH
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
188 OPERATOR VALUE, --field PATH OPERATOR VALUE`` (be careful that the short option is an
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
189 uppercase ``F``, the lower case one being used for Full-Text Search).
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
190
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
191 .. note::
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
192
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
193 Parsed Metadata Filters are not indexed, that means that using them is less efficient
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
194 than using e.g. Full-Text Search. If you want to filter on a text field, it's often a
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
195 good idea to pre-filter using Full-Text Search to have more efficient queries.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
196
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
197 ``PATH`` and ``VALUE`` can be either specified as string, or using JSON syntax (if the
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
198 value can't be decoded as JSON, it is used as plain text).
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
199
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
200 ``PATH`` is the name of the field to use. If you must go beyond root level fields, you can
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
201 use a JSON array to specify each element of the path. If a string is used, it's an object
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
202 key, if a number is used it's an array index. Thus you can use ``title`` to access the
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
203 root title key, or ``'"title"'`` (JSON string escaped for shell) or ``'["title"]'`` (JSON
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
204 array with the "title" string, escaped for shell).
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
205
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
206 .. note::
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
207
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
208 The extra fields ``pubsub_service``, ``pubsub_node`` and  ``node_profile`` are added to
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
209 the result after the query, thus they can't be used as fields for filtering (use the
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
210 direct arguments for that).
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
211
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
212 ``OPERATOR`` indicate how to use the value to make a filter. The currently supported
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
213 operators are:
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
214
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
215 ``==`` or ``eq``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
216 Equality operator, true if field value is the same as given value.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
217
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
218 ``!=`` or ``ne``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
219 Inequality operator, true if the field value is different from given value.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
220
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
221 ``>`` or ``gt``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
222 Greater than, true if the field value is higher than given value. For string, this is
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
223 according to alphabetical order.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
224
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
225 Time Pattern can be used here, see below.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
226
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
227 ``<`` or ``lt``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
228 Lesser than, true if the field value is lower than given value. For string, this is
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
229 according to alphabetical order.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
230
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
231 Time Pattern can be used here, see below.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
232
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
233 ``between``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
234 Given value must be an array with 2 elements. The condition is true if field value is
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
235 between the 2 elements (for string, this is according to alphabetical order).
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
236
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
237 Time Pattern can be used here, see below.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
238
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
239 ``in``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
240 Given value must be an array of elements. Field value must be one of them to make the
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
241 condition true.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
242
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
243 ``not_in``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
244 Given value must be an array of elements. Field value must not be any of them the make
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
245 the condition true.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
246
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
247 ``overlap``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
248 This can be used only on array fields.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
249
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
250 If given value is not already an array, it is put in an array. Condition is true if any
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
251 element of field value match any element of given value. Notably useful to filter on
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
252 tags.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
253
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
254 ``ioverlap``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
255 Same as ``overlap`` but done in a case insensitive way.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
256
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
257 ``disjoint``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
258 This can be used only on array fields.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
259
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
260 If given value is not already an array, it is put in an array. Condition is true if no
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
261 element of field value match any element of given value. Notably useful to filter out
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
262 tags.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
263
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
264 ``idisjoint``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
265 Same as ``disjoint`` but done in a case insensitive way.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
266
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
267 ``like``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
268 Does pattern matching on a string. ``%`` can be used to match zero or more characters
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
269 and ``_`` can be used to match any single character.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
270
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
271 If you're not looking after a specific field, it's better to use Full-Text Search when
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
272 possible.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
273
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
274 ``ilike``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
275 Like ``like`` but done in a case insensitive way.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
276
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
277
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
278 ``not_like``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
279 Same as ``like`` except that condition is true when pattern is **not** matching.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
280
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
281 ``not_ilike``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
282 Same as ``not_like`` but done in a case insensitive way.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
283
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
284
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
285 For ``gt``/``>``, ``lt``/``<`` and ``between``, you can use :ref:`time_pattern` by using
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
286 the syntax ``TP(<time pattern>)`` (see examples below).
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
287
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
288 Ordering
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
289 --------
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
290
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
291 Result ordering can be done by a well know order, or using a parsed data field. Ordering
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
292 default to ``created`` (see below), but this may be changed with ``-o ORDER [FIELD]
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
293 [DIRECTION], --order-by ORDER [FIELD] [DIRECTION]``.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
294
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
295 ``ORDER`` can be one of the following:
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
296
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
297 ``creation``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
298 Order by item creation date. Note that is this the date of creation of the item in cache
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
299 (which most of time should correspond to order of creation of the item in the source
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
300 pubsub service), and this may differ from the date of publication as specified with some
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
301 feature (like blog). This is important when old items are imported, e.g. when they're
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
302 coming from an other blog engine.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
303
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
304 ``modification``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
305 Order by the date when item has last been modified. Modification date is the same as
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
306 creation date if the item has never been modified since it is in cache. The same warning
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
307 as for ``creation`` applies: this is the date of last modification in cache, not the one
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
308 advertised in parsed data.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
309
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
310 ``item_id``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
311 Order by XMPP id of the item. Notably useful when user-friendly ID are used (like it is
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
312 often the case with blogs).
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
313
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
314 ``rank``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
315 Order item by Full-Text Search rank. This one can only be used when Full-Text Search is
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
316 used (via ``-f FTS_QUERY, --fts FTS_QUERY``). Rank is a value indicating how well an
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
317 item match the query. This usually needs to be used with ``desc`` direction, so you get
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
318 most relevant items first.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
319
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
320 ``field``
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
321 This special order indicates that the ordering must be done on an parsed data field. The
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
322 following argument is then the path of the field to used (which can be a plain text name
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
323 of a root field, or a JSON encoded array). An optional direction can be specified as a
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
324 third argument. See examples below.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
325
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
326 examples
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
327 --------
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
328
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
329 Search for blog items cached for the profile ``louise`` which contain the word
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
330 ``Slovakia``::
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
331
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
332 $ li pubsub cache search -t blog -p louise -f Slovakia
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
333
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
334 Show title, publication date and id of blog articles (excluding comments) which have been
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
335 published on Louise's blog during the last 6 months, order them by item id. Here we use an
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
336 empty string as a subtype to exclude comments (for which subtype is ``comment``)::
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
337
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
338 $ li pubsub cache search -t blog -S "" -p louise -s louise@example.net -n urn:xmpp:microblog:0 -F published gt 'TP(6 months ago)' -k id -k published -k title -o item_id
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
339
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
340 Show all blog items from anywhere which are tagged as XMPP or ActivityPub (case
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
341 insensitive) and which have been published in the last month (according to advertised
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
342 publishing date, not cache creation date).
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
343
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
344 We want to order them by descending publication date (again the advertised publication
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
345 date, not cache creation), and we don't want more than 50 results.
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
346
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
347 We do a FTS query there even if it's not mandatory, because it will do an efficient
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
348 pre-filtering::
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
349
d0b66efc6c0e doc (cli/pubsub_cache): `search` command documentation:
Goffi <goffi@goffi.org>
parents: 3669
diff changeset
350 $ li pubsub cache search -f "xmpp OR activitypub" -F tags ioverlap '["xmpp", "activitypub"]' -F published gt 'TP(1 month ago)' -o field published desc -l 50