cerc-io/lotus
10
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 27 Wiki Activity

Add some description to the retrieve command

Browse Source
This commit is contained in:
Łukasz Magiera 2021-11-23 22:23:13 +01:00
parent 135796d4fa
commit 210485d800
2 changed files with 111 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
cli/client_retr.go
View File

@ -93,7 +93,7 @@ func retrieve(ctx context.Context, cctx *cli.Context, fapi lapi.FullNode, sel *l
// no local found, so make a retrieval // no local found, so make a retrieval
if eref == nil { if eref == nil {
var offer lapi.QueryOffer var offer lapi.QueryOffer
minerStrAddr := cctx.String("miner") minerStrAddr := cctx.String("provider")
if minerStrAddr == "" { // Local discovery if minerStrAddr == "" { // Local discovery
offers, err := fapi.ClientFindData(ctx, file, pieceCid) offers, err := fapi.ClientFindData(ctx, file, pieceCid)
@ -216,8 +216,9 @@ var retrFlagsCommon = []cli.Flag{
Usage: "address to send transactions from", Usage: "address to send transactions from",
}, },
&cli.StringFlag{ &cli.StringFlag{
Name: "miner", Name: "provider",
Usage: "miner address for retrieval, if not present it'll use local discovery", Usage: "provider to use for retrieval, if not present it'll use local discovery",
Aliases: []string{"miner"},
}, },
&cli.StringFlag{ &cli.StringFlag{
Name: "maxPrice", Name: "maxPrice",
@ -237,14 +238,47 @@ var clientRetrieveCmd = &cli.Command{
Name: "retrieve", Name: "retrieve",
Usage: "Retrieve data from network", Usage: "Retrieve data from network",
ArgsUsage: "[dataCid outputPath]", 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{ Flags: append([]cli.Flag{
&cli.BoolFlag{ &cli.BoolFlag{
Name: "car", Name: "car",
Usage: "export to a car file instead of a regular file", Usage: "export to a car file instead of a regular file",
}, },
&cli.StringFlag{ &cli.StringFlag{
Name: "datamodel-path-selector", Name: "data-selector",
Usage: "a rudimentary (DM-level-only) text-path selector, allowing for sub-selection within a deal", Aliases: []string{"data-selector-selector"},
Usage: "IPLD datamodel text-path selector, or IPLD json selector",
}, },
}, retrFlagsCommon...), }, retrFlagsCommon...),
Action: func(cctx *cli.Context) error { Action: func(cctx *cli.Context) error {
@ -261,7 +295,7 @@ var clientRetrieveCmd = &cli.Command{
afmt := NewAppFmt(cctx.App) afmt := NewAppFmt(cctx.App)
var s *lapi.Selector 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 s = &sel
} }
@ -350,8 +384,8 @@ var clientRetrieveCatCmd = &cli.Command{
Usage: "list IPLD datamodel links", Usage: "list IPLD datamodel links",
}, },
&cli.StringFlag{ &cli.StringFlag{
Name: "datamodel-path", Name: "data-selector",
Usage: "a rudimentary (DM-level-only) text-path selector", Usage: "IPLD datamodel text-path selector, or IPLD json selector",
}, },
}, retrFlagsCommon...), }, retrFlagsCommon...),
Action: func(cctx *cli.Context) error { Action: func(cctx *cli.Context) error {
@ -372,7 +406,7 @@ var clientRetrieveCatCmd = &cli.Command{
ctx := ReqContext(cctx) ctx := ReqContext(cctx)
afmt := NewAppFmt(cctx.App) afmt := NewAppFmt(cctx.App)
sel := lapi.Selector(cctx.String("datamodel-path")) sel := lapi.Selector(cctx.String("data-selector"))
selp := &sel selp := &sel
if sel == "" { if sel == "" {
selp = nil selp = nil
@ -416,7 +450,7 @@ func pathToSel(psel string, sub builder.SelectorSpec) (lapi.Selector, error) {
var clientRetrieveLsCmd = &cli.Command{ var clientRetrieveLsCmd = &cli.Command{
Name: "ls", Name: "ls",
Usage: "Show object links", Usage: "List object links",
ArgsUsage: "[dataCid]", ArgsUsage: "[dataCid]",
Flags: append([]cli.Flag{ Flags: append([]cli.Flag{
&cli.BoolFlag{ &cli.BoolFlag{
@ -429,8 +463,8 @@ var clientRetrieveLsCmd = &cli.Command{
Value: 1, Value: 1,
}, },
&cli.StringFlag{ &cli.StringFlag{
Name: "datamodel-path", Name: "data-selector",
Usage: "a rudimentary (DM-level-only) text-path selector", Usage: "IPLD datamodel text-path selector, or IPLD json selector",
}, },
}, retrFlagsCommon...), }, retrFlagsCommon...),
Action: func(cctx *cli.Context) error { 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"))) 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) ssb := builder.NewSelectorSpecBuilder(basicnode.Prototype.Any)
dataSelector, err = pathToSel(cctx.String("datamodel-path"), dataSelector, err = pathToSel(cctx.String("data-selector"),
ssb.ExploreUnion( ssb.ExploreUnion(
ssb.Matcher(), ssb.Matcher(),
ssb.ExploreAll( ssb.ExploreAll(
@ -518,9 +552,9 @@ var clientRetrieveLsCmd = &cli.Command{
} else { } else {
jsel := lapi.Selector(fmt.Sprintf(`{"R":{"l":{"depth":%d},":>":{"a":{">":{"|":[{"@":{}},{".":{}}]}}}}}`, cctx.Int("depth"))) 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) 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()))), ssb.ExploreRecursive(selector.RecursionLimitDepth(int64(cctx.Int("depth"))), ssb.ExploreAll(ssb.ExploreUnion(ssb.Matcher(), ssb.ExploreRecursiveEdge()))),
) )
} }

88
documentation/en/cli-lotus.md
View File

@ -427,7 +427,7 @@ COMMANDS:
find Find data in the network find Find data in the network
retrieve Retrieve data from network retrieve Retrieve data from network
cat Show 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 cancel-retrieval Cancel a retrieval deal by deal ID; this also cancels the associated transfer
list-retrievals List retrieval market deals list-retrievals List retrieval market deals
STORAGE: STORAGE:
@ -546,15 +546,49 @@ USAGE:
CATEGORY: CATEGORY:
RETRIEVAL 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: OPTIONS:
--car export to a car file instead of a regular file (default: false) --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 --data-selector value, --data-selector-selector value IPLD datamodel text-path selector, or IPLD json selector
--from value address to send transactions from --from value address to send transactions from
--miner value miner address for retrieval, if not present it'll use local discovery --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) --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 --pieceCid value require data to be retrieved from a specific Piece CID
--allow-local (default: false) --allow-local (default: false)
--help, -h show help (default: false) --help, -h show help (default: false)
``` ```
@ -570,21 +604,21 @@ CATEGORY:
RETRIEVAL RETRIEVAL
OPTIONS: OPTIONS:
--ipld list IPLD datamodel links (default: false) --ipld list IPLD datamodel links (default: false)
--datamodel-path value a rudimentary (DM-level-only) text-path selector --data-selector value IPLD datamodel text-path selector, or IPLD json selector
--from value address to send transactions from --from value address to send transactions from
--miner value miner address for retrieval, if not present it'll use local discovery --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) --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 --pieceCid value require data to be retrieved from a specific Piece CID
--allow-local (default: false) --allow-local (default: false)
--help, -h show help (default: false) --help, -h show help (default: false)
``` ```
### lotus client ls ### lotus client ls
``` ```
NAME: NAME:
lotus client ls - Show object links lotus client ls - List object links
USAGE: USAGE:
lotus client ls [command options] [dataCid] lotus client ls [command options] [dataCid]
@ -593,15 +627,15 @@ CATEGORY:
RETRIEVAL RETRIEVAL
OPTIONS: OPTIONS:
--ipld list IPLD datamodel links (default: false) --ipld list IPLD datamodel links (default: false)
--depth value list links recursively up to the specified depth (default: 1) --depth value list links recursively up to the specified depth (default: 1)
--datamodel-path value a rudimentary (DM-level-only) text-path selector --data-selector value IPLD datamodel text-path selector, or IPLD json selector
--from value address to send transactions from --from value address to send transactions from
--miner value miner address for retrieval, if not present it'll use local discovery --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) --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 --pieceCid value require data to be retrieved from a specific Piece CID
--allow-local (default: false) --allow-local (default: false)
--help, -h show help (default: false) --help, -h show help (default: false)
``` ```