Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
protogrid:json_api_database_views [2018-02-13 10:38] – [data_protos_by_search_term_and_id] 46.140.51.3protogrid:json_api_database_views [2023-01-10 23:16] (current) – [Standard Views Decommissioned With Version 2.6.0] dru
Line 3: Line 3:
 A Database View can be seen as a table with two columns. The first column is called 'key', the second one is called 'value'. The keys have to be unique. A lookup to a view always expects a key, several keys or a range of keys. The response of a lookup consists of all requested keys together with their values. Example for respond: A Database View can be seen as a table with two columns. The first column is called 'key', the second one is called 'value'. The keys have to be unique. A lookup to a view always expects a key, several keys or a range of keys. The response of a lookup consists of all requested keys together with their values. Example for respond:
  
-<code json>+<code javascript>
 { {
   "errors": [],   "errors": [],
-  "protogrid_environment_version": "1.4.10", 
   "result": {   "result": {
     "rows": [     "rows": [
Line 14: Line 13:
           "4bcbdb7f-89c3-4640-b04e-3bd468df7c57"           "4bcbdb7f-89c3-4640-b04e-3bd468df7c57"
         ],         ],
-        "shortname": "CWH ONE", 
         "value": null         "value": null
       },       },
Line 22: Line 20:
           "7e3e7a96-6ea7-4dc7-a58a-1c781ae35e7b"           "7e3e7a96-6ea7-4dc7-a58a-1c781ae35e7b"
         ],         ],
-        "shortname": "DirtKiller 64 -  washing machines", 
         "value": null         "value": null
       },       },
Line 30: Line 27:
           "89e74e40-b0ef-4bc3-8e89-a43a43763087"           "89e74e40-b0ef-4bc3-8e89-a43a43763087"
         ],         ],
-        "shortname": "SuperCleaner 2000 -  washing machines", 
         "value": null         "value": null
       }       }
Line 40: Line 36:
 For details about listings / views and how to request it, please see section about view [[protogrid:api_endpoints|endpoints]]. Please note that all views have the Card id as the last key component due to how Protogrid is implemented on top of CouchDB. In most cases it is useful to specify the start_key and end_key URL parameters with null and {} (empty object) as their last element. This will give all keys matching the other specified keys. For details about listings / views and how to request it, please see section about view [[protogrid:api_endpoints|endpoints]]. Please note that all views have the Card id as the last key component due to how Protogrid is implemented on top of CouchDB. In most cases it is useful to specify the start_key and end_key URL parameters with null and {} (empty object) as their last element. This will give all keys matching the other specified keys.
  
-===== all_by_id =====+For newcomers: In 90% of use cases, the [[#by_proto_and_design_element_and_value_and_sortstring_and_id|"by_proto_and_design_element_and_value_and_sortstring_and_id"]] view fits best. 
 + 
 +===== Protogrid Standard Views ===== 
 + 
 +==== Simple Overall Views ==== 
 + 
 +=== all_by_id ===
 This view basically lists all the ids of all the Cards. The row values are null (i.e. unused). The result is paged, which means that you might need several requests to load all the ids. To load the next page, you can use the "next_card_key" of the previous page as startkey. This view basically lists all the ids of all the Cards. The row values are null (i.e. unused). The result is paged, which means that you might need several requests to load all the ids. To load the next page, you can use the "next_card_key" of the previous page as startkey.
  
Line 49: Line 51:
  
 Example respond: Example respond:
-<code json>+<code javascript >
 { {
   "errors": [],   "errors": [],
-  "protogrid_environment_version": "1.4.10", 
   "result": {   "result": {
     "next_card_key": [     "next_card_key": [
-    "51b97f49-3262-4339-a8c7-2e8166887761"+      "51b97f49-3262-4339-a8c7-2e8166887761"
     ],     ],
     "rows": [     "rows": [
-    +      
-      "key":+        "key":
-      "4d523d95-31dd-4cb3-b60a-c974404e4ffd" +          "4d523d95-31dd-4cb3-b60a-c974404e4ffd" 
-      ], +        ], 
-      "shortname": {}, +        "value": null
-      "value": null+
       },       },
       ...       ...
-      ] +    ]
-    }+
   }   }
-</code> 
- 
-===== all_protos_by_id ===== 
-This view contains all Protos by id. The value contains shortname and a list of design_elements. 
- 
-Example request to get the first 5 protos: 
-<code> 
-https://example.protogrid.com/api/v2/apps/produktekatalog/views/all_protos_by_id?limit=5 
-</code> 
- 
-Example respond: 
-<code json> 
-{ 
-    "errors": [], 
-    "protogrid_environment_version": "1.4.14", 
-    "result": { 
-        "next_card_key": "&&protosTableViewProto", 
-        "rows": [ 
-            { 
-                "key": "&&allTableViewProto", 
-                "shortname": "Proto:All Cards By ID", 
-                "value": { 
-                    "design_elements": [ 
-                        "name", 
-                        "plural_name", 
-                        "theme_color", 
-                        "enable_attachments", 
-                        "enable_filtering_for_id", 
-                        "script_library", 
-                        "editor_role", 
-                        "allow_editing_cards_to_users", 
-                        "show_cards_to_users", 
-                        "creator_role", 
-                        "automatically_created_tableview_proto", 
-                        "comment", 
-                        "card_design_elements", 
-                        "cards_based_on_this" 
-                    ], 
-                    "shortname": { 
-                        "en": "Proto:All Cards By ID" 
-                    } 
-                } 
-            }, 
-            ... 
-        ] 
-    } 
 } }
 </code> </code>
    
-===== by_id =====+=== by_id ===
 This View contains all non-deleted and non-hidden Card IDs as keys. The value is null. This gives you fast access to all the Card IDs in your Application. This can be useful for example when doing some kind of synchronization and checking for new documents.  This View contains all non-deleted and non-hidden Card IDs as keys. The value is null. This gives you fast access to all the Card IDs in your Application. This can be useful for example when doing some kind of synchronization and checking for new documents. 
  
Line 125: Line 78:
 https://example.protogrid.com/api/v2/apps/produktekatalog/views/by_id?start_key=[null]&end_key=[{}]&include_cards=true https://example.protogrid.com/api/v2/apps/produktekatalog/views/by_id?start_key=[null]&end_key=[{}]&include_cards=true
 </code> </code>
 +
 +Please note that the "include_cards" parameter has a high cost in terms of performance. We therefore recommend using this functionality very economically, i.e. on as few view rows as possible.
  
 Example respond (be aware, that this Card is a System Card and therefore looks different to the typical Cards): Example respond (be aware, that this Card is a System Card and therefore looks different to the typical Cards):
-<code json>+<code javascript >
 { {
     "errors": [],     "errors": [],
-    "protogrid_environment_version": "1.4.14", 
     "result": {     "result": {
         "next_card_key": [         "next_card_key": [
Line 233: Line 187:
                     "&&adminMenuDefinition"                     "&&adminMenuDefinition"
                 ],                 ],
-                "shortname": "Menu:Administration", 
                 "value": null                 "value": null
             },             },
Line 242: Line 195:
 </code> </code>
  
-===== by_id_and_value ===== +==== Overall Views With Filtering/Sorting ====
-This view contains all  non-deleted and non-hidden Cards. The value is raw Card. In typical use, you want to use this view to load your Cards, since you do not want to load Cards which are deleted or hidden by accident.+
  
-**Be aware**: This is one of the very few views, where the key is **NOT** surrounded by "[ ... ]"!+=== by_sortstring_and_id ===
  
-Example request to get the Cards whose ID is within the range "a3c8b1b5-ea36-4ae0-f1bd-5366543ae36c" to "a5a8815d-9cff-4489-9e21-6f54163408ee": +=== by_design_element_and_sortstring_and_id ===
-<code> +
-https://example.protogrid.com/api/v2/apps/produktekatalog/views/by_id_and_value?start_key="a3c8b1b5-ea36-4ae0-f1bd-5366543ae36c"&end_key="a5a8815d-9cff-4489-9e21-6f54163408ee" +
-</code> +
- +
-Example respond (do not be confused by the special content of the Card: It is a Multilanguage Card): +
-<code json> +
-+
-    "errors": [], +
-    "protogrid_environment_version": "1.4.14", +
-    "result":+
-        "rows":+
-            { +
-                "key": "a3c8b1b5-ea36-4ae0-f1bd-5366543ae36c", +
-                "shortname": "Product Catalog", +
-                "value":+
-                    "_id": "a3c8b1b5-ea36-4ae0-f1bd-5366543ae36c", +
-                    "_rev": "4-001d21026ea44eccea11cabe45358dbf", +
-                    "denormalized":+
-                        "&&multilanguageProto":+
-                            "allow_editing_cards_to_users": 0, +
-                            "creator_role": "", +
-                            "editor_role": "", +
-                            "show_cards_to_users":+
-                        }, +
-                        "a3c8b1b5-ea36-4ae0-f1bd-5366543ae36c":+
-                            "displayable_type":+
-                                "de": "DynamicCard", +
-                                "en": "DynamicCard" +
-                            }, +
-                            "shortname":+
-                                "de": "Product Catalog", +
-                                "en": "Product Catalog" +
-                            } +
-                        } +
-                    }, +
-                    "design_elements":+
-                        { +
-                            "definition_key": "en", +
-                            "value": "Product Catalog" +
-                        }, +
-                        { +
-                            "definition_key": "de", +
-                            "value": "Produktekatalog" +
-                        } +
-                    ], +
-                    "get_design_element": {}, +
-                    "get_design_element_properties": {}, +
-                    "get_key": {}, +
-                    "get_proto_key": {}, +
-                    "get_shortname": {}, +
-                    "get_type": {}, +
-                    "get_value": {}, +
-                    "last_healed": "2016-02-17T05:31:30", +
-                    "modification_log":+
-                        { +
-                            "time": "2016-03-23T12:11:47", +
-                            "user": "a77b8462-ec5f-4b8e-9bc3-29fe8784c69e" +
-                        }, +
-                        { +
-                            "time": "2016-03-23T12:13:11", +
-                            "user": "a77b8462-ec5f-4b8e-9bc3-29fe8784c69e" +
-                        }, +
-                        { +
-                            "time": "2016-03-23T12:16:46", +
-                            "user": "a77b8462-ec5f-4b8e-9bc3-29fe8784c69e" +
-                        }, +
-                        { +
-                            "time": "2016-03-23T18:02:59", +
-                            "user": "6ab4c76c-07a3-4edd-99aa-c61923866020" +
-                        } +
-                    ], +
-                    "proto_key": "&&multilanguageProto", +
-                    "reader_role_key": "", +
-                    "set_design_element_value": {}, +
-                    "set_element_value": {} +
-                } +
-            }, +
-            { +
-                "key": "a5a8815d-9cff-4489-9e21-6f54163408ee", +
-                ... +
-            } +
-        ] +
-    } +
-+
-</code> +
- +
-===== deleted_by_id ===== +
-This view contains the IDs of all the deleted Cards as keys. The value is null. The request and response are analog to view [[#by_id|"by_id"]]. +
- +
-===== by_proto_and_id ===== +
-This view contains all non-deleted and non-hidden Cards with corresponding Proto by id. The key is composed of the Proto key and the Card key. The value is null. This view can be used to get all Cards belonging to a special Proto given the Proto key. +
- +
-Example Request to get all Cards belonging to the Proto with key "12532072-0d76-4457-8cf8-7847d0470738": +
-<code> +
-https://example.protogrid.com/api/v2/apps/produktekatalog/views/by_proto_and_id?start_key=["12532072-0d76-4457-8cf8-7847d0470738", null]&end_key=["12532072-0d76-4457-8cf8-7847d0470738", {}] +
-</code> +
- +
-We use "null" and "{}" as boundaries for the Card key.  +
- +
-Example respond: +
-<code json> +
-+
-    "errors": [], +
-    "protogrid_environment_version": "1.4.14", +
-    "result":+
-        "rows":+
-            { +
-                "key":+
-                    "12532072-0d76-4457-8cf8-7847d0470738", +
-                    "4bcbdb7f-89c3-4640-b04e-3bd468df7c57" +
-                ], +
-                "shortname": "CWH ONE", +
-                "value": null +
-            }, +
-            ... +
-        ] +
-    } +
-+
-</code> +
- +
-Out of this, you now know the Card keys of all Cards based on this Proto. To get the content of the Cards, you need to get the second part of every key, read it into an array and the request all Cards within the array using the view [[#by_id_and_value|by_id_and_value]]. +
- +
-===== by_proto_and_shortname_and_id ===== +
-This View contains all non-deleted and non-hidden Cards with corresponding Proto and shortname by id. This means the key is composed of the Proto key, the shortname and the Card ID. Example: +
-<code json> +
-["12532072-0d76-4457-8cf8-7847d0470738", "SuperCleaner 2000 - washing machines", "89e74e40-b0ef-4bc3-8e89-a43a43763087"+
-</code> +
-The value is null. +
-Since the Shortname may differ in different languages, there is one entry per selected language. This may also mean, that if the Shortname is the same for several languages, you get the result several times. +
- +
-This allows to get the cards based on the Shortname as follows: +
-<code> +
-https://example.protogrid.com/api/v2/apps/produktekatalog/views/by_proto_and_id?start_key=["2843c3cf-abee-45a5-a869-e0ea9703c7c0", "sewer cover", null]&end_key=["2843c3cf-abee-45a5-a869-e0ea9703c7c0", "sewer cover", {}] +
-</code> +
- +
-Example respond: +
-<code json> +
-+
-    "errors": [], +
-    "protogrid_environment_version": "1.4.14", +
-    "result":+
-        "rows":+
-            { +
-                "key":+
-                    "2843c3cf-abee-45a5-a869-e0ea9703c7c0", +
-                    "sewer cover", +
-                    "f8f9f426-0d72-42bf-bd00-c9164d500334" +
-                ], +
-                "shortname": "sewer cover", +
-                "value": null +
-            }, +
-            { +
-                "key":+
-                    "2843c3cf-abee-45a5-a869-e0ea9703c7c0", +
-                    "sewer cover", +
-                    "f8f9f426-0d72-42bf-bd00-c9164d500334" +
-                ], +
-                "shortname": "sewer cover", +
-                "value": null +
-            } +
-        ] +
-    } +
-+
-</code> +
- +
-===== by_search_term_and_id ===== +
-This view contains Cards for a certain search term by id. The key is composed of the search term and the Card key. Search term means a specific string, for which you want to find all Cards containing this string in the values. You may not find Cards having this string only in the labels of the fields. Example: +
-<code json> +
-["behavior", "1475e62a-47d7-4a29-98c2-c89f50edd497"+
-</code> +
-The value is null. +
- +
-**Be aware**: The search only goes over values stored in this Card. This may differ from the visual representation Card. For example when Card A references another Card, you see the Shortname of the referenced Card (say "wishes an offer") in the corresponding relation field. Nevertheless, the Card only stores the Card key of the related Card (say "c18bc1c2-5499-49cc-90e0-f06b4af1474f"), therefore you will not find Card A when searching for Cards containing "wishes"+
- +
-Example request to find all cards containing the word "behavior": +
-<code> +
-https://example.protogrid.com/api/v2/apps/produktekatalog/views/by_search_term_and_id?start_key=["behavior", null]&end_key=["behavior",{}] +
-</code> +
- +
-Example response: +
-<code json> +
-+
-    "errors": [], +
-    "protogrid_environment_version": "1.4.14", +
-    "result":+
-        "next_card_key":+
-            "behavior", +
-            "ba9859e1-68ad-4004-b8e0-c4f0812edf20" +
-        ], +
-        "rows":+
-            { +
-                "key":+
-                    "behavior", +
-                    "1475e62a-47d7-4a29-98c2-c89f50edd497" +
-                ], +
-                "shortname": "ScriptLibrary:Server-ScriptLibrary Next Steps", +
-                "value": null +
-            }, +
-            { +
-                "key":+
-                    "behavior", +
-                    "1475e62a-47d7-4a29-98c2-c89f50edd497" +
-                ], +
-                "shortname": "ScriptLibrary:Server-ScriptLibrary Next Steps", +
-                "value": null +
-            }, +
-            { +
-                "key":+
-                    "behavior", +
-                    "ba9859e1-68ad-4004-b8e0-c4f0812edf20" +
-                ], +
-                "shortname": "ScriptLibrary:Server-ScriptLibrary Products", +
-                "value": null +
-            }, +
-            ... +
-        ] +
-    } +
-+
-</code> +
- +
-You might have duplicates in the code due to several occurrences of the same search term on the same Card. +
- +
-===== deleted_by_search_term_and_id ===== +
-This view contains all deleted Cards for a certain search term by id. The value is null. The request and response are analog to view [[#by_search_term_and_id|"by_search_term_and_id"]]. +
- +
-===== by_proto_and_search_term_and_id ===== +
-This view contains all non-deleted and non-hidden Cards by proto and searchterm (see also [[#by_search_term_and_id|by_search_term_and_id]]. Therefore the key is composed of the Proto key, the searchterm and the Card key. Example: +
-<code> +
-["9c2bdd7d-05bd-4d16-8339-11116e737b3a", "wants", "21f28df9-b0fd-431d-a773-5c6f58ff94a2"+
-</code> +
- +
-Example Request to get all Cards of Proto "9c2bdd7d-05bd-4d16-8339-11116e737b3a" containing the string "wants": +
-<code> +
-https://example.protogrid.com/api/v2/apps/produktekatalog/views/by_proto_and_search_term_and_id?start_key=["9c2bdd7d-05bd-4d16-8339-11116e737b3a", "wants", null]&end_key=["9c2bdd7d-05bd-4d16-8339-11116e737b3a", "wants",{}] +
-</code> +
- +
-Example response: +
-<code json> +
-+
-    "errors": [], +
-    "protogrid_environment_version": "1.4.14", +
-    "result":+
-        "rows":+
-            { +
-                "key":+
-                    "9c2bdd7d-05bd-4d16-8339-11116e737b3a", +
-                    "wants", +
-                    "21f28df9-b0fd-431d-a773-5c6f58ff94a2" +
-                ], +
-                "shortname": "Priscilla Molesworth - wishes an offer - Luxor 600t", +
-                "value": null +
-            }, +
-            ... +
-        ] +
-    } +
-+
-</code>+
  
-===== by_design_element_and_value_and_id ===== +=== by_design_element_and_value_and_sortstring_and_id === 
-This view contains all non-deleted and non-hidden Cards by design_element, date and id. Therefore the key is composed of the key of the design element, the value of the design element and the id of the Card. Example:+This view contains all non-deleted and non-hidden Cards by design_element, date and id. Therefore the key is composed of the key of the design element, the value of the design element, the Card sorting string and the Card key. Example:
 <code> <code>
-["234486c7-939f-49f4-88b2-6fd51369a1d9", "Basic Toilet 2016 ", "d81047c2-0d92-48ee-a352-f0c8d4e63b2b"]+["234486c7-939f-49f4-88b2-6fd51369a1d9", "Basic Toilet 2016 ", "Basic Toilet 2016 ", "d81047c2-0d92-48ee-a352-f0c8d4e63b2b"]
 </code> </code>
 The value is null. The value is null.
  
-Example request to get all Cards, where the name (in my example having with fieldkey "ed2c109d-a825-4b97-a0bb-31c13185408d") starts with "n" or "o":+Example request to get all Cards, where the name (in my example having with fieldkey "816950eb-1b70-41e2-89f5-5400f9636345") starts with "n" or "o":
 <code> <code>
-https://example.protogrid.com/api/v2/apps/produktekatalog/views/by_design_element_and_value_and_id?start_key=["816950eb-1b70-41e2-89f5-5400f9636345", "n", null]&end_key=["816950eb-1b70-41e2-89f5-5400f9636345", "m", {}]+https://example.protogrid.com/api/v2/apps/produktekatalog/views/by_design_element_and_value_and_sortstring_and_id?start_key=["816950eb-1b70-41e2-89f5-5400f9636345","n",null,null]&end_key=["816950eb-1b70-41e2-89f5-5400f9636345","m",{},{}]
 </code> </code>
  
 Example response: Example response:
-<code json>+<code javascript >
 { {
     "errors": [],     "errors": [],
-    "protogrid_environment_version": "1.4.14", 
     "result": {     "result": {
         "rows": [         "rows": [
Line 528: Line 222:
                 "key": [                 "key": [
                     "816950eb-1b70-41e2-89f5-5400f9636345",                     "816950eb-1b70-41e2-89f5-5400f9636345",
 +                    "night knight PRO",
                     "night knight PRO",                     "night knight PRO",
                     "9a5f37ab-30a7-4c91-b99f-f573a1c7d1b9"                     "9a5f37ab-30a7-4c91-b99f-f573a1c7d1b9"
                 ],                 ],
-                "shortname": "night knight PRO", 
                 "value": null                 "value": null
             },             },
Line 538: Line 232:
                     "816950eb-1b70-41e2-89f5-5400f9636345",                     "816950eb-1b70-41e2-89f5-5400f9636345",
                     "nightTable 2.0",                     "nightTable 2.0",
 +                    "nightTable 2.0 - furniture",
                     "f6e2f9c9-e061-46f4-ab8f-a2594c2b38ae"                     "f6e2f9c9-e061-46f4-ab8f-a2594c2b38ae"
                 ],                 ],
-                "shortname": "nightTable 2.0 - furniture", 
                 "value": null                 "value": null
             }             }
Line 548: Line 242:
 </code> </code>
  
 +==== Proto Specific Views ====
  
-===== deleted_by_design_element_and_value_and_id===== +=== by_proto_and_sortstring_and_id ==== 
-This view contains all deleted Cards for a certain search term by design_elementdate and id. The value is null. The request and response are analog to view [[#by_design_element_and_value_and_id|"by_design_element_and_value_and_id"]].+This view contains all non-deleted and non-hidden Cards with corresponding Proto by id. The key is composed of the Proto keythe Card sorting string and the Card key. The value is null. This view can be used to get all Cards belonging to a special Proto given the Proto key.
  
-===== by_proto_and_design_element_and_value_and_id ===== +Example Request to get all Cards belonging to the Proto with key "12532072-0d76-4457-8cf8-7847d0470738":
-This view contains all non-deleted and non-hidden Cards by  Proto, design_element, date and id. Therefore the keys is composed of the Proto key, the fieldkey of the design element, the value of the design element and the Card key. Example:+
 <code> <code>
-["9c2bdd7d-05bd-4d16-8339-11116e737b3a", "&&created", "2016-09-17T20:47:52", "398f0b4c-cbb9-42c9-b4e0-e5c2e7913ec5"]+https://example.protogrid.com/api/v2/apps/produktekatalog/views/by_proto_and_sortstring_and_id?start_key=["12532072-0d76-4457-8cf8-7847d0470738",null,null]&end_key=["12532072-0d76-4457-8cf8-7847d0470738",{},{}]
 </code> </code>
-The value is null. You typically want to use this view to query on system fields such as "&&created" or "&&shortname", which are available on all Protos. 
  
-Example Request to find all Cards based on Proto "12532072-0d76-4457-8cf8-7847d0470738" which were modified in November 2016: +We use "null" and "{}" as boundaries for the Card key. 
-<code> +
-https://example.protogrid.com/api/v2/apps/produktekatalog/views/by_proto_and_design_element_and_value_and_id?start_key=["12532072-0d76-4457-8cf8-7847d0470738", "&&modified", "2016-11-01T00:00:00", null]&end_key=["12532072-0d76-4457-8cf8-7847d0470738", "&&modified", "2016-11-30T23:59:59", {}+
-</code>+
  
-===== relational_definitions_by_id_and_related_proto ===== +Example respond
-This view contains all relational definitions field key and Proto Key. This means that assuming we have a Relation Field (with the field key "359a18bf-2fb6-4d6d-afe4-3b6283f35b50") whose related Proto has the Proto Key "2843c3cf-abee-45a5-a869-e0ea9703c7c0", the key looks as follows: +<code javascript >
-<code> +
-["359a18bf-2fb6-4d6d-afe4-3b6283f35b50", "2843c3cf-abee-45a5-a869-e0ea9703c7c0"+
-</code> +
-The value is null.  +
- +
-Example Request to find the Proto to which the relation field with key "5d41e440-7ddb-4837-bd28-ed32839c4d7a" is related: +
-<code> +
-https://example.protogrid.com/api/v2/apps/produktekatalog/views/relational_definitions_by_id_and_related_proto?start_key=["5d41e440-7ddb-4837-bd28-ed32839c4d7a", null]&end_key=["5d41e440-7ddb-4837-bd28-ed32839c4d7a", {}] +
-</code> +
- +
- +
-===== data_protos_by_id ===== +
-This view lists all [[protgrid:proto#data_proto|data Protos]] by id. The value is null. You may want to use this to list all data Protos or to find a given Proto. +
- +
-Example request to get all data Protos: +
-<code> +
-https://example.protogrid.com/api/v2/apps/produktekatalog/views/data_protos_by_id?start_key=[null]&end_key=[{}]&include_cards=true +
-</code> +
- +
-Example response+
-<code json>+
 { {
     "errors": [],     "errors": [],
-    "protogrid_environment_version": "1.4.15", 
     "result": {     "result": {
         "rows": [         "rows": [
             {             {
-                "doc": { 
-                    "_id": "12532072-0d76-4457-8cf8-7847d0470738", 
-                    "_rev": "60-5cbfade7a369b55b58688fe0934a715d", 
-                    "definition_type": "Proto", 
-                    "denormalized": { 
-                        "08a1bb54-4927-4736-9a7a-44c677d7ec0d": { 
-                            "displayable_type": { 
-                                "de": "DynamicCard", 
-                                "en": "DynamicCard" 
-                            }, 
-                            "shortname": { 
-                                "de": "Products", 
-                                "en": "Products" 
-                            } 
-                        }, 
-                        ... 
-                    }, 
-                    "design_elements": [ 
-                        { 
-                            "disable_label": false, 
-                            "display_priority": 10, 
-                            "element_type": "MultilanguageText", 
-                            "grid_size_setting": 0, 
-                            "help_text": "&&mlkey_proto_name_help_text", 
-                            "hidden": false, 
-                            "label_multilanguage_key": "&&mlkey_card_name", 
-                            "list_priority": 0, 
-                            "multiple_values_setting": 0, 
-                            "name": "name", 
-                            "requirement_setting": 1, 
-                            "show_to_users": 0, 
-                            "user_enabled_setting": 0, 
-                            "value": "c4472c16-c7c3-4e11-eba9-73b69fca32cf", 
-                            "value_type": "key" 
-                        }, 
-                        ... 
-                    ], 
-                    "get_shortname": {}, 
-                    "hidden": false, 
-                    "last_healed": "2016-07-06T14:17:13", 
-                    "modification_log": [ 
-                        { 
-                            "time": "2016-03-23T12:23:37", 
-                            "user": "a77b8462-ec5f-4b8e-9bc3-29fe8784c69e" 
-                        }, 
-                        ... 
-                    ], 
-                    "reader_role_key": "", 
-                    "set_element_value": {}, 
-                    "title_multilanguage_key": "&&mlkey_proto_definition_key", 
-                    "user_creatable": true 
-                }, 
                 "key": [                 "key": [
-                    "12532072-0d76-4457-8cf8-7847d0470738"+                    "12532072-0d76-4457-8cf8-7847d0470738", 
 +                    "CWH ONE", 
 +                    "4bcbdb7f-89c3-4640-b04e-3bd468df7c57"
                 ],                 ],
-                "shortname": "Proto:Product", 
                 "value": null                 "value": null
             },             },
Line 657: Line 274:
 </code> </code>
  
-===== data_protos_by_search_term_and_id ===== +=== by_proto_and_design_element_and_sortstring_and_id ===
-This view contains all [[protgrid:proto#data_proto|data Protos]] for a certain search term and by id. Possible search terms are the linked roles, the linked overview proto or name parts of the chosen color (such as "light" or "green"). The value is null.+
  
-Example request to get all data Protos linked with the role "201d4953-b50b-4833-921f-9e3ee2bfdac3":+=== by_proto_and_design_element_and_value_and_sortstring_and_id === 
 +This view contains all non-deleted and non-hidden Cards by  Proto, design_element, date and id. Therefore the keys is composed of the Proto key, the fieldkey of the design element, the value of the design element, the Card sorting string and the Card key. Example:
 <code> <code>
-https://example.protogrid.com/api/v2/apps/produktekatalog/views/data_protos_by_search_term_and_id?start_key=["201d4953-b50b-4833-921f-9e3ee2bfdac3", null]&end_key=["201d4953-b50b-4833-921f-9e3ee2bfdac3", {}]+["9c2bdd7d-05bd-4d16-8339-11116e737b3a", "&&created", "2016-09-17T20:47:52", "398f0b4c-cbb9-42c9-b4e0-e5c2e7913ec5"]
 </code> </code>
 +The value is null. You typically want to use this view to query on system fields such as "&&created" or "&&shortname", which are available on all Protos.
  
-Example response: +Example Request to find all Cards based on Proto "12532072-0d76-4457-8cf8-7847d0470738" whos price ("ed2c109d-a825-4b97-a0bb-31c13185408d") lies between 400 and 500:
-<code json> +
-+
-    "errors": [], +
-    "protogrid_environment_version": "1.4.15", +
-    "result":+
-        "next_card_key":+
-            "201d4953-b50b-4833-921f-9e3ee2bfdac3", +
-            "9c2bdd7d-05bd-4d16-8339-11116e737b3a" +
-        ], +
-        "rows":+
-            { +
-                "key":+
-                    "201d4953-b50b-4833-921f-9e3ee2bfdac3", +
-                    "12532072-0d76-4457-8cf8-7847d0470738" +
-                ], +
-                "shortname": "Proto:Product", +
-                "value": null +
-            }, +
-            ... +
-        ] +
-    } +
-+
-</code> +
- +
-===== datetime_field_definitions_by_id ===== +
-This view contains all datetime field definitions by id. The value is null. +
- +
-Example request to find all datetime field definitions of an app:+
 <code> <code>
-https://example.protogrid.com/api/v2/apps/ppad/views/datetime_field_definitions_by_id?start_key=[null]&end_key=[{}]+https://example.protogrid.com/api/v2/apps/produktekatalog/views/by_proto_and_design_element_and_value_and_sortstring_and_id?start_key=["12532072-0d76-4457-8cf8-7847d0470738","ed2c109d-a825-4b97-a0bb-31c13185408d","400",null,null]&end_key=["12532072-0d76-4457-8cf8-7847d0470738","ed2c109d-a825-4b97-a0bb-31c13185408d","500",{},{}]
 </code> </code>
  
 Example response: Example response:
-<code json>+<code javascript >
 { {
     "errors": [],     "errors": [],
-    "protogrid_environment_version": "1.4.15", 
     "result": {     "result": {
         "rows": [         "rows": [
             {             {
                 "key": [                 "key": [
-                    "69de5836-8fba-43b7-980e-1ad6d0434733"+                    "12532072-0d76-4457-8cf8-7847d0470738", 
 +                    "ed2c109d-a825-4b97-a0bb-31c13185408d", 
 +                    "449", 
 +                    "CWH ONE - toilet", 
 +                    "4bcbdb7f-89c3-4640-b04e-3bd468df7c57"
                 ],                 ],
-                "shortname": "Report date", 
                 "value": null                 "value": null
             },             },
             {             {
                 "key": [                 "key": [
-                    "f346a8aa-d351-48e7-af5f-cde54493a445"+                    "12532072-0d76-4457-8cf8-7847d0470738", 
 +                    "ed2c109d-a825-4b97-a0bb-31c13185408d", 
 +                    "499", 
 +                    "ForestFire 2016 - lawn mover", 
 +                    "e086c668-500b-4acf-982c-df4f3be65a6b"
                 ],                 ],
-                "shortname": "Due date", 
                 "value": null                 "value": null
             }             }
Line 724: Line 319:
 </code> </code>
  
-===== datetime_field_definitions_by_search_term_and_id ===== +==== Views for Deleted Cards ====
-This view contains all datetime field_definitions for a certain search term by id. Possible search terms are parts of the shortname of the definition card as well as the linked MultiLanguage Card for the label.  The value is null.+
  
-Example request to find the datetime field definition, which label is linked to the MultiLanguage Card "3370e075-b1b0-4a8f-8b06-de4694481f0b": +=== deleted_by_sortstring_and_id === 
-<code> +This view contains the IDs of all the deleted Cards as keysThe value is nullThe request and response are analog to view [[#by_sortstring_and_id|"by_sortstring_and_id"]].
-https://example.protogrid.com/api/v2/apps/ppad/views/datetime_field_definitions_by_search_term_and_id?start_key=["3370e075-b1b0-4a8f-8b06-de4694481f0b",null]&end_key=["3370e075-b1b0-4a8f-8b06-de4694481f0b",{}] +
-</code>+
  
-Example response: +=== deleted_by_design_element_and_sortstring_and_id === 
-<code json> +This view contains all deleted Cards sorted by a certain design elementThe value is nullThe request and response are analog to view [[#by_design_element_and_sortstring_and_id|"by_design_element_and_sortstring_and_id"]]. 
-+ 
-    "errors": [], +=== deleted_by_design_element_and_value_and_sortstring_and_id === 
-    "protogrid_environment_version": "1.4.15", +This view contains all deleted Cards by a certain Proto, design_element, value, sortstring and id. The value is null. The request and response are analog to view [[#by_design_element_and_value_and_sortstring_and_id|"by_design_element_and_value_and_sortstring_and_id"]].
-    "result":+
-        "rows": [ +
-            { +
-                "key": [ +
-                    "3370e075-b1b0-4a8f-8b06-de4694481f0b", +
-                    "f346a8aa-d351-48e7-af5f-cde54493a445" +
-                ], +
-                "shortname": "Due date", +
-                "value": null +
-            } +
-        ] +
-    } +
-+
-</code>+
  
-===== related_keys_by_id ===== +==== Views for Navigation in Relational Tree (Up / Down) ====
-This view contains all Cards with related keys by id. The value contains the related keys.+
  
-**Be aware**: This is one of the very few views, where the key is **NOT** surrounded by "[ ... ]"!+=== related_keys_by_id === 
 +This view contains all Cards by idThe value contains the related keys.
  
 Example request to find all Cards related to the Card "234486c7-939f-49f4-88b2-6fd51369a1d9": Example request to find all Cards related to the Card "234486c7-939f-49f4-88b2-6fd51369a1d9":
 <code> <code>
-https://example.protogrid.com/api/v2/apps/produktekatalog/views/related_keys_by_id?keys=["234486c7-939f-49f4-88b2-6fd51369a1d9"]+https://example.protogrid.com/api/v2/apps/produktekatalog/views/related_keys_by_id?keys=[["234486c7-939f-49f4-88b2-6fd51369a1d9"]]
 </code> </code>
  
 Example response: Example response:
-<code json>+<code javascript >
 { {
     "errors": [],     "errors": [],
-    "protogrid_environment_version": "1.4.15", 
     "result": {     "result": {
         "rows": [         "rows": [
             {             {
-                "key": "234486c7-939f-49f4-88b2-6fd51369a1d9", +                "key": 
-                "shortname": "name",+                    "234486c7-939f-49f4-88b2-6fd51369a1d9" 
 +                ],
                 "value": [                 "value": [
                     [                     [
Line 816: Line 394:
 </code> </code>
  
-===== by_relating_key ===== +=== relating_cards_by_related_key_and_id === 
-This view contains all Cards with the related key by id. The key is composed of the two card keys. The value is null.+This view contains all Relating Cards of the (Related) Card specified by key. The key is composed of the Related Card key and the Relating Card key. The value is null.
  
-Example request to find all Cards related to the Card "626f04f7-179d-40d7-99f0-9e54343abf98":+Example request to find all Cards relating to the (Related) Card with key "626f04f7-179d-40d7-99f0-9e54343abf98":
 <code> <code>
-https://example.protogrid.com/api/v2/apps/produktekatalog/views/by_relating_key?start_key=["626f04f7-179d-40d7-99f0-9e54343abf98", null]&end_key=["626f04f7-179d-40d7-99f0-9e54343abf98", {}]+https://example.protogrid.com/api/v2/apps/produktekatalog/views/relating_cards_by_related_key_and_id?start_key=["626f04f7-179d-40d7-99f0-9e54343abf98",null]&end_key=["626f04f7-179d-40d7-99f0-9e54343abf98",{}]
 </code> </code>
  
 Example response: Example response:
-<code json>+<code javascript >
 { {
     "errors": [],     "errors": [],
-    "protogrid_environment_version": "1.4.15", 
     "result": {     "result": {
         "rows": [         "rows": [
Line 836: Line 413:
                     "00ded64d-5e1b-42a1-a61e-f8e46c0c552a"                     "00ded64d-5e1b-42a1-a61e-f8e46c0c552a"
                 ],                 ],
-                "shortname": "Liguan 2.0 TDI", 
                 "value": null                 "value": null
             },             },
Line 844: Line 420:
                     "50a9098b-bd4e-47fe-9e99-7d8f1d43517a"                     "50a9098b-bd4e-47fe-9e99-7d8f1d43517a"
                 ],                 ],
-                "shortname": "Paolo Schnuffi - wishes a callback ", 
                 "value": null                 "value": null
             },             },
Line 852: Line 427:
                     "5d068708-9546-4536-94c6-da27b6a909b2"                     "5d068708-9546-4536-94c6-da27b6a909b2"
                 ],                 ],
-                "shortname": "Freddie Mac - wishes a callback  - nightTable 2.0", 
                 "value": null                 "value": null
             },             },
Line 860: Line 434:
                     "fa6f178c-a398-4852-a3b3-7e66978c9a65"                     "fa6f178c-a398-4852-a3b3-7e66978c9a65"
                 ],                 ],
-                "shortname": "EcoDischarger", 
                 "value": null                 "value": null
             },             },
Line 868: Line 441:
                     "fbf79fc6-2da1-41f2-9954-1606dbe3fa01"                     "fbf79fc6-2da1-41f2-9954-1606dbe3fa01"
                 ],                 ],
-                "shortname": "Liguan 2.0 TDI", 
                 "value": null                 "value": null
             }             }
Line 875: Line 447:
 } }
 </code> </code>
-===== tableview_data_by_id =====+ 
 +==== Views for Direct Human Readable Presentation ===
 + 
 +=== tableview_data_by_id ===
 This view contains all Cards contained in a tableview by id. The value contains the raw card.  This view contains all Cards contained in a tableview by id. The value contains the raw card. 
  
Line 884: Line 459:
  
 Example response: Example response:
-<code json>+<code javascript >
 { {
     "errors": [],     "errors": [],
-    "protogrid_environment_version": "1.4.15", 
     "result": {     "result": {
         "rows": [         "rows": [
             {             {
-                "key": "5f12ccf6-9de0-4796-d366-106e4b7b8af9", +                "key": 
-                "shortname": "Card: 5f12ccf6-9de0-4796-d366-106e4b7b8af9",+                    "5f12ccf6-9de0-4796-d366-106e4b7b8af9" 
 +                ],
                 "value": {                 "value": {
                     "#": [                     "#": [
Line 933: Line 508:
 </code> </code>
  
- +=== shortname_objects_by_id === 
-===== shortname_by_language_objects_by_id ===== +This view contains all Cards which contain shortname data by id. The value contains the shortnames by language.
-This view contains all Cards which contains shortname data by id. The value contains the shortnames by language.+
  
 Example request to get the shortnames of the Card with key "a0e6717f-c613-404a-bc08-a090311c651c": Example request to get the shortnames of the Card with key "a0e6717f-c613-404a-bc08-a090311c651c":
 <code> <code>
-https://example.protogrid.com/api/v2/apps/produktekatalog/views/shortname_by_language_objects_by_id?keys=[["a0e6717f-c613-404a-bc08-a090311c651c"]]+https://example.protogrid.com/api/v2/apps/produktekatalog/views/shortname_objects_by_id?keys=[["a0e6717f-c613-404a-bc08-a090311c651c"]]
 </code> </code>
  
 Example response: Example response:
-<code json>+<code javascript >
 { {
     "errors": [],     "errors": [],
-    "protogrid_environment_version": "1.4.15", 
     "result": {     "result": {
         "rows": [         "rows": [
             {             {
-                "key": "a0e6717f-c613-404a-bc08-a090311c651c", +                "key": 
-                "shortname": "Priscilla Molesworth - wishes an offer",+                    "a0e6717f-c613-404a-bc08-a090311c651c" 
 +                ],
                 "value": {                 "value": {
                     "de": "Priscilla Molesworth - wishes an offer",                     "de": "Priscilla Molesworth - wishes an offer",
Line 962: Line 536:
 </code> </code>
  
-===== sums_by_proto_and_design_element  ===== +===== Views of Dedicated Search Dialog Boxes ===== 
-Sums over the values of a field for all Cards of a Proto. Depending on the field type, this uses the following functions: +It is also possible to access the views of dedicated [[protogrid:TableView#Search Dialog Boxes|Search Dialog Box]] from the JSON APIJust use the Card ID of the Search Dialog Box as view name.
-  - For number fields it produces the sum of values over the field. +
-  - For text fields it produces the word count over all text entries. +
-  - For relation fields it produces the number of stored relations. +
-  - For date/time fields it produces the number of stored date/time values.+
  
-Example Request to count the number of words in all names (field key "816950eb-1b70-41e2-89f5-5400f9636345"of Proto "Product"(key "12532072-0d76-4457-8cf8-7847d0470738"):+Hint: For straight forward API usage in most cases it is recommended to use Search Dialog Boxes in "Simple Keys in JSON API only" display mode. 
 + 
 +Please note that Datetime Fields in Dedicated Search Boxes are indexed slightly differently than in normal views: If the date-time value is configured as a fixed filter field, the time component will always be set to 0 (example: "2021-11-11T00:00:00.000Z"). If the date-time value is configured as a sort field or filter field with range (greater/less than option enabled), the time portion is left as it is (example: "2021-11-11T22:22:00.000Z")
 + 
 +Example Request:
 <code> <code>
-https://example.protogrid.com/api/v2/apps/produktekatalog/views/sums_by_proto_and_design_element?keys=[["12532072-0d76-4457-8cf8-7847d0470738", "816950eb-1b70-41e2-89f5-5400f9636345"]]+https://example.protogrid.com/api/v2/apps/produktekatalog/views/869a18bf-2fb6-4d6d-afe4-3b6283f35ba3
 </code> </code>
  
-===== sums_by_proto_and_design_element_and_condition ===== +The key depends on the individually configured Filter Fields for the acessed Search Dialog Box.
-Sums over the values of a field for all Cards of a Proto given a condition from another field. This key requires query keys with four components: +
-  - The Proto key +
-  - The design element key for the field to sum over +
-  - The design element key for the condition field +
-  - The conditional value in the field specified in component (3) +
-Example: What is the sum over all values in the “Total” field in the Proto “Invoice”, given that the relation field “customer” holds the key for “John Smith”? +
  
-Depending on the field type, this uses the following functions: +===== Change Log ===== 
-  - For number fields it produces the sum of values over the field+==== Standard Views Decommissioned With Version 2.1.5 ==== 
-  - For text fields it produces the word count over all text entries. +  * by_id_and_value 
-  - For relation fields it produces the number of stored relations. +  * by_proto_and_search_term_and_id 
-  - For date/time fields it produces the number of stored date/time values.+  * by_search_term_and_id 
 +  * data_protos_by_id 
 +  * data_protos_by_search_term_and_id 
 +  * datetime_field_definitions_by_id 
 +  * datetime_field_definitions_by_search_term_and_id 
 +  * deleted_by_design_element_and_value_and_id 
 +  * deleted_by_id 
 +  * deleted_by_search_term_and_id 
 +  * logs_by_time_and_id 
 +  * navroot_candidates_by_design_element_and_value_and_id 
 +  * navroot_candidates_by_id 
 +  * navroot_candidates_by_search_term_and_id 
 +  * number_field_definitions_by_id 
 +  * number_field_definitions_by_search_term_and_id 
 +  * relational_definitions_by_id_and_related_proto 
 +  * text_field_definitions_by_id 
 +  * text_field_definitions_by_search_term_and_id
  
-Example Request to count the number of words in the names (field key "816950eb-1b70-41e2-89f5-5400f9636345"of the Proto "Product"(key "12532072-0d76-4457-8cf8-7847d0470738"where the product group (field key "359a18bf-2fb6-4d6d-afe4-3b6283f35b50") is furniture (key "fde10c41-7e7c-45a2-bbf3-3065de5e05ad")+==== Standard Views Decommissioned With Version 2.2.1 ==== 
-<code+  * by_design_element_and_value_and_id 
-https://example.protogrid.com/api/v2/apps/produktekatalog/views/sums_by_proto_and_design_element_and_condition?keys=[["12532072-0d76-4457-8cf8-7847d0470738","816950eb-1b70-41e2-89f5-5400f9636345","359a18bf-2fb6-4d6d-afe4-3b6283f35b50","fde10c41-7e7c-45a2-bbf3-3065de5e05ad"]+  * by_proto_and_id 
-</code>+  * by_proto_and_design_element_and_value_and_id 
 +  * deleted_by_proto_and_design_element_and_value_and_id 
 +  * navroot_candidates_by_design_element_and_sortstring_and_id 
 +  * navroot_candidates_by_design_element_and_value_and_sortstring_and_id 
 +  * sums_by_proto_and_design_element 
 +  * sums_by_proto_and_design_element_and_condition 
 +  * datetime_field_definitions_by_sortstring_and_id 
 +  * datetime_field_definitions_by_search_term_and_sortstring_and_id 
 +  * text_field_definitions_by_sortstring_and_id 
 +  * text_field_definitions_by_search_term_and_sortstring_and_id 
 +  * number_field_definitions_by_sortstring_and_id 
 +  * number_field_definitions_by_search_term_and_sortstring_and_id 
 +  * all_protos_by_id 
 +  * all_agents_by_id 
 +  * all_connectors_by_url_name 
 + 
 +==== Adjustments to Views With Version 2.2.2 ==== 
 +  - All views: If a view is requested with the "descending" parameter set to true "start_key" and "end_key" must now be exchanged. 
 +  All views: All string values as well as sortstrings are now cut off after 300 characters. 
 +  All views: The separator between human readable values and keys is now "\u0009" instead of "\u9999"
 +  All views: The second last column "sortstring" is now indexed in a shorter manner: "<SORTSTRING>" instead of "<PROTO KEY>\u9999<SORTSTRING>\u9999<CARD KEY>" 
 +  - Dedicated Search Boxes: Now all filters must be set. An empty filter field in a Search Dialog Boxes now means a filter for those Cards where the target field is also empty. 
 +  Dedicated Search Boxes: Datetime Fields in Dedicated Search Boxes are now indexed slightly differently than in normal views: If the date-time value is configured as a fixed filter field, the time component will always be set to 0 (example: “2021-11-11T00:00:00.000Z”). If the date-time value is configured as a sort field or filter field with range (greater/less than option enabled), the time portion is left as it is (example: “2021-11-11T22:22:00.000Z”). 
 +  Dedicated Search Boxes with "sortable" display mode: Columns are now indexed in a shorter manner
 +    * For Relation/Tag Field values: "SORTSTRING >\u0009<KEY>" instead of "<SORTSTRING>\u9999<KEY>\u9999<KEY>" 
 +    * For other field values"<VALUE>" instead of "\u9999<VALUE>\u9999<VALUE>" 
 +    * Note: It is anyway recommended to use Search Dialog Boxes with display mode “Simple Keys in JSON API only” (ienon-sortable). 
 +  - In views "by_design_element_and_sortstring_and_id", "by_proto_and_design_element_and_sortstring_and_id" and "deleted_by_design_element_and_sortstring_and_id" the design element's sortstrings are now indexed in a shorter manner: 
 +    * For Relation/Tag Field values: "< SORTSTRING >\u0009<KEY>" instead of "<SORTSTRING>\u9999<KEY>\u9999<KEY>" 
 +    * For other field values: "<VALUE>" instead of "\u9999<VALUE>\u9999<VALUE>" 
 +    * Note: If you don't explicitly need sorting by design element value is anyway recommended to use the views "by_design_element_and_value_and_sortstring_and_id", by_proto_and_design_element_and_value_and_sortstring_and_id"" or "deleted_by_design_element_and_value_and_sortstring_and_id"
 +  - In views "by_design_element_and_sortstring_and_id", "by_proto_and_design_element_and_sortstring_and_id" and "deleted_by_design_element_and_sortstring_and_id" there is a new column for the Card's sortstring after the design element's sortstring. Example: 
 +    * View columns of "by_design_element_and_sortstring_and_id" before: ["816950eb-1b70-41e2-89f5-5400f9636345", "nightTable 2.0", "9a5f37ab-30a7-4c91-b99f-f573a1c7d1b9"
 +    * View columns of by_design_element_and_sortstring_and_id"" now: ["816950eb-1b70-41e2-89f5-5400f9636345", "nightTable 2.0", "nightTable 2.0 furniture", "9a5f37ab-30a7-4c91-b99f-f573a1c7d1b9"]
  
 +==== Standard Views Decommissioned With Version 2.6.0 ====
 +  * by_search_term_and_sortstring_and_id
 +  * by_proto_and_search_term_and_sortstring_and_id
 +  * deleted_by_search_term_and_sortstring_and_id
 +  * navroot_candidates_by_sortstring_and_id
 +  * navroot_candidates_by_search_term_and_sortstring_and_id
 +  * data_protos_by_sortstring_and_id
 +  * data_protos_by_search_term_and_sortstring_and_id
Print/export