doc(LAB-3532): update importing_assets_and_metadata.md recipe & tutorial

Author: paulruelle

docs/sdk/tutorials/importing_assets_and_metadata.md

@@ -51,7 +51,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "First, let's install and import the required modules."
+    "First, let's install and import the required modules.\n"
    ]
   },
   {
@@ -273,48 +273,58 @@
     "\n",
     "- `imageUrl`\n",
     "- `text`\n",
-    "- `url`"
+    "- `url`\n",
+    "\n",
+    "\n",
+    "## Setting metadata properties"
    ]
   },
   {
    "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "As an optional step, you can set data types for each type of your metadata.\n",
-    "The default data type is `string`, but setting some of your metadata as `number` can really help apply filters on your assets later on.\n",
+    "As an optional step, you can define properties for each type of your metadata.\n",
+    "These properties allow you to control:\n",
     "\n",
-    "Note that we don't need to set data types for `imageUrl`, `text`, and `url`."
+    "- The data type (`string` or `number`)\n",
+    "- Whether the metadata is filterable in project queue\n",
+    "- Visibility of each metadata to labelers and reviewers\n"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "{'id': 'cllamrwgl00670j393poh2t4j',\n",
-       " 'metadataTypes': {'sensitiveData': 'string',\n",
-       "  'customConsensus': 'number',\n",
-       "  'uploadedFromCloud': 'string',\n",
-       "  'modelLabelErrorScore': 'number'}}"
-      ]
-     },
-     "execution_count": null,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
+   "outputs": [],
    "source": [
     "kili.update_properties_in_project(\n",
     "    project_id=project_id,\n",
-    "    metadata_types={\n",
-    "        \"customConsensus\": \"number\",\n",
-    "        \"sensitiveData\": \"string\",\n",
-    "        \"uploadedFromCloud\": \"string\",\n",
-    "        \"modelLabelErrorScore\": \"number\",\n",
+    "    metadata_properties={\n",
+    "        \"customConsensus\": {\n",
+    "            \"type\": \"number\",\n",
+    "            \"filterable\": True,\n",
+    "            \"visibleByLabeler\": True,\n",
+    "            \"visibleByReviewer\": True,\n",
+    "        },\n",
+    "        \"sensitiveData\": {\n",
+    "            \"type\": \"string\",\n",
+    "            \"filterable\": True,\n",
+    "            \"visibleByLabeler\": False,  # Hide this from labelers\n",
+    "            \"visibleByReviewer\": True,\n",
+    "        },\n",
+    "        \"uploadedFromCloud\": {\n",
+    "            \"type\": \"string\",\n",
+    "            \"filterable\": True,\n",
+    "            \"visibleByLabeler\": True,\n",
+    "            \"visibleByReviewer\": True,\n",
+    "        },\n",
+    "        \"modelLabelErrorScore\": {\n",
+    "            \"type\": \"number\",\n",
+    "            \"filterable\": True,\n",
+    "            \"visibleByLabeler\": True,\n",
+    "            \"visibleByReviewer\": True,\n",
+    "        },\n",
     "    },\n",
     ")"
    ]
@@ -324,6 +334,17 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "> **Note**: The previous `metadata_types` parameter is deprecated. Please use metadata_properties instead. If you use metadata_types, it will still work but will be converted to metadata_properties internally with default visibility and filterability settings.\n",
+    "\n",
+    "If you don't specify all properties, default values will be used:\n",
+    "\n",
+    "```\n",
+    "filterable: true\n",
+    "type: 'string'\n",
+    "visibleByLabeler: true\n",
+    "visibleByReviewer: true\n",
+    "```\n",
+    "\n",
     "Now we can add metadata to our assets:"
    ]
   },
@@ -355,19 +376,17 @@
     "            \"sensitiveData\": \"yes\",\n",
     "            \"uploadedFromCloud\": \"no\",\n",
     "            \"modelLabelErrorScore\": 50,\n",
-    "            # Add metadata that will be visible to labelers in the labeling interface:\n",
-    "            \"imageUrl\": \"www.example.com/image_1.png\",\n",
-    "            \"text\": \"some text for asset 1\",\n",
+    "            \"imageUrl\": \"https://placehold.co/600x400/EEE/31343C\",\n",
+    "            \"text\": \"Some text for asset 1\",\n",
     "            \"url\": \"www.example-website.com\",\n",
     "        },\n",
     "        {\n",
     "            \"customConsensus\": 40,\n",
     "            \"sensitiveData\": \"no\",\n",
     "            \"uploadedFromCloud\": \"yes\",\n",
     "            \"modelLabelErrorScore\": 30,\n",
-    "            # Add metadata that will be visible to labelers in the labeling interface:\n",
-    "            \"imageUrl\": \"www.example.com/image_2.png\",\n",
-    "            \"text\": \"some text for asset 2\",\n",
+    "            \"imageUrl\": \"https://placehold.co/600x400/EEE/31343C\",\n",
+    "            \"text\": \"Some text for asset 2\",\n",
     "            \"url\": \"www.example-website.com\",\n",
     "        },\n",
     "    ],\n",
@@ -378,7 +397,10 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In the labeling interface, we can see that the assets have some metadata:"
+    "> **Note** : alternatively, you can use `kili.set_metadata` or `kili.add_metadata` methods.\n",
+    "\n",
+    "\n",
+    "In the labeling interface, we can see that the assets have some metadata (note that `sensitiveData` will be hidden from labelers based on our settings)."
    ]
   },
   {
@@ -390,7 +412,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "![image.png](attachment:0bea7811-9a67-461c-b716-319de1343ac8.png)"
+    "![image.png](./img/json_metadata.png)"
    ]
   },
   {
@@ -441,7 +463,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We've successfully set up a Kili project, imported assets to it, and finally added some metadata to our assets. Well done!"
+    "We've successfully set up a Kili project, imported assets to it, and finally added some metadata to our assets with advanced property settings. Well done!"
    ]
   }
  ],