diff --git a/content/en/guides/core/registry/link_version.md b/content/en/guides/core/registry/link_version.md index 33c7c409db..85c513ca22 100644 --- a/content/en/guides/core/registry/link_version.md +++ b/content/en/guides/core/registry/link_version.md @@ -3,63 +3,113 @@ menu: default: identifier: link_version parent: registry -title: Link an artifact version to a registry +title: Link an artifact version to a collection weight: 5 --- -Link artifact versions to a collection to make them available to other members in your organization. +Link an artifact version to a collection to make it available to other members in your organization. Linking an artifact to a collection brings that artifact version from a private, project-level scope, to a shared organization level scope. -When you link an artifact to a registry, this "publishes" that artifact to that registry. Any user that has access to that registry can access the linked artifact versions in the collection. +You can [link an artifact version to a collection]({{< relref "/guides/core/registry/link_version.md#link-an-artifact-version-to-a-collection" >}}) programmatically with the W&B Python SDK or interactively with the W&B App. -In other words, linking an artifact to a registry collection brings that artifact version from a private, project-level scope, to a shared organization level scope. +When you link an artifact version to a collection, W&B creates a linked version of that artifact in the collection. The linked version points to the source artifact version that is logged to a run within a project. You can view the linked version in the collection and the source version in the project where it was logged. -{{% alert %}} + +{{% /alert %}} --> + +{{% alert %}} +Watch a [video demonstrating linking a version](https://www.youtube.com/watch?v=2i_n1ExgO0A) (8 min). {{% /alert %}} -## Link an artifact to a collection +## Link an artifact to a collection -Link an artifact version to a collection interactively or programmatically. +Based on your use case, follow the instructions described in the tabs below to link an artifact version. {{% alert %}} -Before you link an artifact to a registry, check the types of artifacts that collection permits. For more information about collection types, see "Collection types" within [Create a collection]({{< relref "./create_collection.md" >}}). +Before you start, check the following: +* The types of artifacts that collection permits. For more information about collection types, see "Collection types" within [Create a collection]({{< relref "./create_collection.md" >}}). +* The registry that the collection belongs to already exists. To check that the registry exists, navigate to the [Registry App and search for]({{< relref "/guides/core/registry/search_registry" >}}) the name of the registry. {{% /alert %}} -Based on your use case, follow the instructions described in the tabs below to link an artifact version. -{{% alert %}} + + + + {{< tabpane text=true >}} {{% tab header="Python SDK" %}} -{{% alert %}} -Watch a [video demonstrating linking a version](https://www.youtube.com/watch?v=2i_n1ExgO0A) (8 min). -{{% /alert %}} -Programmatically link an artifact version to a collection with [`wandb.init.Run.link_artifact()`]({{< relref "/ref/python/experiments/run.md#link_artifact" >}}). + +Programmatically link an artifact version to a collection with [`wandb.init.Run.link_artifact()`]({{< relref "/ref/python/experiments/run.md#link_artifact" >}}) or [`wandb.Artifact.link()`]({{< relref "/ref/python/experiments/artifact.md#method-artifactlink" >}}). Use `wandb.init.Run.link_artifact()` if you are linking an artifact version [within the context of a run](#link-an-artifact-version-within-the-context-of-a-run). Use `wandb.Artifact.link()` if you are linking an artifact version [outside the context of a run](#link-an-artifact-version-outside-the-context-of-a-run). {{% alert %}} -Before you link an artifact to a collection, ensure that the registry that the collection belongs to already exists. To check that the registry exists, navigate to the Registry app on the W&B App UI and search for the name of the registry. +`wandb.Artifact.link()` does not require you to initialize a run with `wandb.init()`. `wandb.init.Run.link_artifact()` requires you to initialize a run with `wandb.init()`. {{% /alert %}} -Use the `target_path` parameter to specify the collection and registry you want to link the artifact version to. The target path consists of the prefix "wandb-registry", the name of the registry, and the name of the collection separated by a forward slashes: +For both approaches, specify the name of the artifact (`wandb.Artifact(type=""`), the type of artifact (`wandb.Artifact(type=""`), and the `target_path` of the collection and registry you want to link the artifact version to. + + +The target path consists of the prefix `"wandb-registry"`, the name of the registry, and the name of the collection separated by a forward slashes: ```text wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME} ``` +
+ + + +
+ +### Link an artifact version within the context of a run -Copy and paste the code snippet below to link an artifact version to a collection within an existing registry. Replace values enclosed in `<>` with your own: +When you use `wandb.init.Run.link_artifact()`, you need to initialize a run with `wandb.init()`. This means that a run is created in your W&B project. + +Copy and paste the code snippet below. Replace values enclosed in `<>` with your own: ```python import wandb +entity = "" # Your team entity +project = "" # The name of the project that contains your artifact + # Initialize a run -run = wandb.init( - entity = "", - project = "" -) +with wandb.init(entity = entity, project = project) as run: + + # Create an artifact object + # The type parameter specifies both the type of the + # artifact object and the collection type + artifact = wandb.Artifact(name = "", type = "") + + # Add the file to the artifact object. + # Specify the path to the file on your local machine. + artifact.add_file(local_path = "") + + # Specify the collection and registry to link the artifact to + REGISTRY_NAME = "" + COLLECTION_NAME = "" + target_path=f"wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}" + + # Link the artifact to the collection + run.link_artifact(artifact = artifact, target_path = target_path) +``` + +
+ +### Link an artifact version outside the context of a run + +When you use `wandb.Artifact.link()`, you do not need to initialize a run with `wandb.init()`. This means that a run is not created in your W&B project. The artifact version is linked to the collection without being associated with a run. + +Copy and paste the code snippet below. Replace values enclosed in `<>` with your own: + +```python +import wandb # Create an artifact object # The type parameter specifies both the type of the @@ -70,17 +120,18 @@ artifact = wandb.Artifact(name = "", type = "") # Specify the path to the file on your local machine. artifact.add_file(local_path = "") +# Save the artifact +artifact.save() + # Specify the collection and registry to link the artifact to REGISTRY_NAME = "" COLLECTION_NAME = "" target_path=f"wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}" # Link the artifact to the collection -run.link_artifact(artifact = artifact, target_path = target_path) +artifact.link(target_path = target_path) ``` -{{% alert %}} -If you want to link an artifact version to the Model registry or the Dataset registry, set the artifact type to `"model"` or `"dataset"`, respectively. -{{% /alert %}} + {{% /tab %}} {{% tab header="Registry App" %}} @@ -116,10 +167,10 @@ If you want to link an artifact version to the Model registry or the Dataset reg +{{% /alert %}} --> + -View a linked artifact's metadata, version data, usage, lineage information and more in the Registry App. +Once an artifact is linked, you can [view a linked artifact's metadata, version data, usage, lineage information]({{< relref "/guides/core/registry/link_version.md#view-linked-artifacts-in-a-registry" >}}) and more in the Registry App. ## View linked artifacts in a registry