From 210485d800eb087da9fa9fff8ba91841a41cd2ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Magiera?= Date: Tue, 23 Nov 2021 22:23:13 +0100 Subject: [PATCH] Add some description to the retrieve command --- cli/client_retr.go | 66 +++++++++++++++++++------- documentation/en/cli-lotus.md | 88 ++++++++++++++++++++++++----------- 2 files changed, 111 insertions(+), 43 deletions(-) diff --git a/cli/client_retr.go b/cli/client_retr.go index 6a23dd14a..3674ad68a 100644 --- a/cli/client_retr.go +++ b/cli/client_retr.go @@ -93,7 +93,7 @@ func retrieve(ctx context.Context, cctx *cli.Context, fapi lapi.FullNode, sel *l // no local found, so make a retrieval if eref == nil { var offer lapi.QueryOffer - minerStrAddr := cctx.String("miner") + minerStrAddr := cctx.String("provider") if minerStrAddr == "" { // Local discovery offers, err := fapi.ClientFindData(ctx, file, pieceCid) @@ -216,8 +216,9 @@ var retrFlagsCommon = []cli.Flag{ Usage: "address to send transactions from", }, &cli.StringFlag{ - Name: "miner", - Usage: "miner address for retrieval, if not present it'll use local discovery", + Name: "provider", + Usage: "provider to use for retrieval, if not present it'll use local discovery", + Aliases: []string{"miner"}, }, &cli.StringFlag{ Name: "maxPrice", @@ -237,14 +238,47 @@ var clientRetrieveCmd = &cli.Command{ Name: "retrieve", Usage: "Retrieve data from network", ArgsUsage: "[dataCid outputPath]", + Description: `Retrieve data from the Filecoin network. + +The retrieve command will attempt to find a provider make a retrieval deal with +them. In case a provider can't be found, it can be specified with the --provider +flag. + +By default the data will be interpreted as DAG-PB UnixFSv1 File. Alternatively +a CAR file containing the raw IPLD graph can be exported by setting the --car +flag. + +Partial Retrieval: + +The --data-selector flag can be used to specify a sub-graph to fetch. The +selector can be specified as either IPLD datamodel text-path selector, or IPLD +json selector. + +In case of unixfs retrieval, the selector must point at a single root node, and +match the entire graph under that node. + +In case of CAR retrieval, the selector must have one common "sub-root" node. + +Examples: + +- Retrieve a file by CID + $ lotus client retrieve Qm... my-file.txt + +- Retrieve a file by CID from f0123 + $ lotus client retrieve --provider f0123 Qm... my-file.txt + +- Retrieve a first file from a specified directory + $ lotus client retrieve --data-selector /Links/0/Hash Qm... my-file.txt +`, Flags: append([]cli.Flag{ &cli.BoolFlag{ Name: "car", Usage: "export to a car file instead of a regular file", }, &cli.StringFlag{ - Name: "datamodel-path-selector", - Usage: "a rudimentary (DM-level-only) text-path selector, allowing for sub-selection within a deal", + Name: "data-selector", + Aliases: []string{"data-selector-selector"}, + Usage: "IPLD datamodel text-path selector, or IPLD json selector", }, }, retrFlagsCommon...), Action: func(cctx *cli.Context) error { @@ -261,7 +295,7 @@ var clientRetrieveCmd = &cli.Command{ afmt := NewAppFmt(cctx.App) var s *lapi.Selector - if sel := lapi.Selector(cctx.String("datamodel-path-selector")); sel != "" { + if sel := lapi.Selector(cctx.String("data-selector")); sel != "" { s = &sel } @@ -350,8 +384,8 @@ var clientRetrieveCatCmd = &cli.Command{ Usage: "list IPLD datamodel links", }, &cli.StringFlag{ - Name: "datamodel-path", - Usage: "a rudimentary (DM-level-only) text-path selector", + Name: "data-selector", + Usage: "IPLD datamodel text-path selector, or IPLD json selector", }, }, retrFlagsCommon...), Action: func(cctx *cli.Context) error { @@ -372,7 +406,7 @@ var clientRetrieveCatCmd = &cli.Command{ ctx := ReqContext(cctx) afmt := NewAppFmt(cctx.App) - sel := lapi.Selector(cctx.String("datamodel-path")) + sel := lapi.Selector(cctx.String("data-selector")) selp := &sel if sel == "" { selp = nil @@ -416,7 +450,7 @@ func pathToSel(psel string, sub builder.SelectorSpec) (lapi.Selector, error) { var clientRetrieveLsCmd = &cli.Command{ Name: "ls", - Usage: "Show object links", + Usage: "List object links", ArgsUsage: "[dataCid]", Flags: append([]cli.Flag{ &cli.BoolFlag{ @@ -429,8 +463,8 @@ var clientRetrieveLsCmd = &cli.Command{ Value: 1, }, &cli.StringFlag{ - Name: "datamodel-path", - Usage: "a rudimentary (DM-level-only) text-path selector", + Name: "data-selector", + Usage: "IPLD datamodel text-path selector, or IPLD json selector", }, }, retrFlagsCommon...), Action: func(cctx *cli.Context) error { @@ -453,9 +487,9 @@ var clientRetrieveLsCmd = &cli.Command{ dataSelector := lapi.Selector(fmt.Sprintf(`{"R":{"l":{"depth":%d},":>":{"a":{">":{"|":[{"@":{}},{".":{}}]}}}}}`, cctx.Int("depth"))) - if cctx.IsSet("datamodel-path") { + if cctx.IsSet("data-selector") { ssb := builder.NewSelectorSpecBuilder(basicnode.Prototype.Any) - dataSelector, err = pathToSel(cctx.String("datamodel-path"), + dataSelector, err = pathToSel(cctx.String("data-selector"), ssb.ExploreUnion( ssb.Matcher(), ssb.ExploreAll( @@ -518,9 +552,9 @@ var clientRetrieveLsCmd = &cli.Command{ } else { jsel := lapi.Selector(fmt.Sprintf(`{"R":{"l":{"depth":%d},":>":{"a":{">":{"|":[{"@":{}},{".":{}}]}}}}}`, cctx.Int("depth"))) - if cctx.IsSet("datamodel-path") { + if cctx.IsSet("data-selector") { ssb := builder.NewSelectorSpecBuilder(basicnode.Prototype.Any) - jsel, err = pathToSel(cctx.String("datamodel-path"), + jsel, err = pathToSel(cctx.String("data-selector"), ssb.ExploreRecursive(selector.RecursionLimitDepth(int64(cctx.Int("depth"))), ssb.ExploreAll(ssb.ExploreUnion(ssb.Matcher(), ssb.ExploreRecursiveEdge()))), ) } diff --git a/documentation/en/cli-lotus.md b/documentation/en/cli-lotus.md index 051293ed6..ad286703c 100644 --- a/documentation/en/cli-lotus.md +++ b/documentation/en/cli-lotus.md @@ -427,7 +427,7 @@ COMMANDS: find Find data in the network retrieve Retrieve data from network cat Show data from network - ls Show object links + ls List object links cancel-retrieval Cancel a retrieval deal by deal ID; this also cancels the associated transfer list-retrievals List retrieval market deals STORAGE: @@ -546,15 +546,49 @@ USAGE: CATEGORY: RETRIEVAL +DESCRIPTION: + Retrieve data from the Filecoin network. + +The retrieve command will attempt to find a provider make a retrieval deal with +them. In case a provider can't be found, it can be specified with the --provider +flag. + +By default the data will be interpreted as DAG-PB UnixFSv1 File. Alternatively +a CAR file containing the raw IPLD graph can be exported by setting the --car +flag. + +Partial Retrieval: + +The --data-selector flag can be used to specify a sub-graph to fetch. The +selector can be specified as either IPLD datamodel text-path selector, or IPLD +json selector. + +In case of unixfs retrieval, the selector must point at a single root node, and +match the entire graph under that node. + +In case of CAR retrieval, the selector must have one common "sub-root" node. + +Examples: + +- Retrieve a file by CID + $ lotus client retrieve Qm... my-file.txt + +- Retrieve a file by CID from f0123 + $ lotus client retrieve --provider f0123 Qm... my-file.txt + +- Retrieve a first file from a specified directory + $ lotus client retrieve --data-selector /Links/0/Hash Qm... my-file.txt + + OPTIONS: - --car export to a car file instead of a regular file (default: false) - --datamodel-path-selector value a rudimentary (DM-level-only) text-path selector, allowing for sub-selection within a deal - --from value address to send transactions from - --miner value miner address for retrieval, if not present it'll use local discovery - --maxPrice value maximum price the client is willing to consider (default: 0 FIL) - --pieceCid value require data to be retrieved from a specific Piece CID - --allow-local (default: false) - --help, -h show help (default: false) + --car export to a car file instead of a regular file (default: false) + --data-selector value, --data-selector-selector value IPLD datamodel text-path selector, or IPLD json selector + --from value address to send transactions from + --provider value, --miner value provider to use for retrieval, if not present it'll use local discovery + --maxPrice value maximum price the client is willing to consider (default: 0 FIL) + --pieceCid value require data to be retrieved from a specific Piece CID + --allow-local (default: false) + --help, -h show help (default: false) ``` @@ -570,21 +604,21 @@ CATEGORY: RETRIEVAL OPTIONS: - --ipld list IPLD datamodel links (default: false) - --datamodel-path value a rudimentary (DM-level-only) text-path selector - --from value address to send transactions from - --miner value miner address for retrieval, if not present it'll use local discovery - --maxPrice value maximum price the client is willing to consider (default: 0 FIL) - --pieceCid value require data to be retrieved from a specific Piece CID - --allow-local (default: false) - --help, -h show help (default: false) + --ipld list IPLD datamodel links (default: false) + --data-selector value IPLD datamodel text-path selector, or IPLD json selector + --from value address to send transactions from + --provider value, --miner value provider to use for retrieval, if not present it'll use local discovery + --maxPrice value maximum price the client is willing to consider (default: 0 FIL) + --pieceCid value require data to be retrieved from a specific Piece CID + --allow-local (default: false) + --help, -h show help (default: false) ``` ### lotus client ls ``` NAME: - lotus client ls - Show object links + lotus client ls - List object links USAGE: lotus client ls [command options] [dataCid] @@ -593,15 +627,15 @@ CATEGORY: RETRIEVAL OPTIONS: - --ipld list IPLD datamodel links (default: false) - --depth value list links recursively up to the specified depth (default: 1) - --datamodel-path value a rudimentary (DM-level-only) text-path selector - --from value address to send transactions from - --miner value miner address for retrieval, if not present it'll use local discovery - --maxPrice value maximum price the client is willing to consider (default: 0 FIL) - --pieceCid value require data to be retrieved from a specific Piece CID - --allow-local (default: false) - --help, -h show help (default: false) + --ipld list IPLD datamodel links (default: false) + --depth value list links recursively up to the specified depth (default: 1) + --data-selector value IPLD datamodel text-path selector, or IPLD json selector + --from value address to send transactions from + --provider value, --miner value provider to use for retrieval, if not present it'll use local discovery + --maxPrice value maximum price the client is willing to consider (default: 0 FIL) + --pieceCid value require data to be retrieved from a specific Piece CID + --allow-local (default: false) + --help, -h show help (default: false) ```