> For the complete documentation index, see [llms.txt](https://www.csvpath.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.csvpath.org/topics/higher-level-topics/organizing-inbound-data/how-data-progresses-through-csvpath-framework/validation-and-upgrading/named-paths-reference-queries.md). # Named-paths Reference Queries ## How are references used? References are used to run individual csvpaths or subsets of csvpaths in named-paths groups. For named-paths references their form is: ```xquery $root.csvpaths.name_one.name_two ``` The four sections are: * Root: a named-file name, named-path name, or named-result name * `csvpaths`: the datatype that indicates we are working with named-paths * `name_one`: the most important id/name/date, etc. we're pointing to (`name_one` is the underlying name of this field, but you won't see it too often) * `name_three`: a secondary id/name/date, etc. that helps determine what the reference is to {% hint style="warning" %} References from CsvPath Validation Language that pick out variables from other runs are a case where you can use a # to point to variables from a specific csvpath instance in the other results, or even an earlier csvpath instance in the currently running results. A reference of this type might look like: ``` $mypaths#myinstance.variables.city ``` This reference says to pull the value of the `city` variable from the `myinstance` csvpath variables from the most recent `mypaths` named-results run. If you didn't use `#myinstance` you would be pulling the `city` variable from the union of all the variable sets created in the most recent run of `mypaths`. Since two csvpath instances might both leave behind their own `city` variable with a different value you might want to be more specific. {% endhint %} Like named-file references, named-paths references use "pointers". A pointer looks like a colon followed by a word or number. Pointers enable dynamic references. For named-paths, the pointers are: * `:from` — used to indicate a run should start from a certain csvpath * `:to` — like `:from`, but indicating the run should stop with a certain csvpath * `:n` *(n = any integer from `0` to `99`)* — indicates which csvpath to return from the group {% hint style="danger" %} As noted above, in some few cases you can split the root, name\_one, and name\_three path segments using a `#`. In fact, grammatically, you can always do this; however, the support for `#` separated words having a good effect is inconsistent and the intended usage has not yet settled. You might see the values created by a `#` referred to as `root_minor` and `name_two` and `name_four`. But again, it is not common. Unless directions say to use the capability, you should not. {% endhint %} ## Examples Named-paths references are simple. They only need to give dynamic control over which csvpaths within the named-paths group to run. A named-paths reference does that by using the :from and :to pointers to indicate the starting or stopping csvpaths. If there is no pointer the reference is to the specific csvpath named. You can refer to a specific csvpath by name or by a colon-number pointer. ``` $invoices.csvpaths.cleanup:from ``` This reference says to do a run of the `invoices` named-paths starting from the `cleanup` csvpath. Or, to be more precise, it references the specific csvpath statements — but that typically means we're setting up a named-paths group run. It is, of course, equally easy to pass a reference to `PathsManager.get_named_paths()` and get back a list of the csvpath statements. Let's say that the invoices named-paths looks like: ```bash ~ id: print date ~ $[0][ @day = today() print("Today is $.variables.day")] ---- CSVPATH ---- ~ id: cleanup ~ $[*][ replace(#city, uppercase(#city)) ] ---- CSVPATH ---- ~ id: add line number ~ $[*][ append("line", line_number())] ``` The reference would run the second (`cleanup`) and third (`add line number`) csvpaths in the group. The `print date` csvpath would not run. ``` $invoices.csvpaths.cleanup:1 ``` Using the same example, this reference would return only the second csvpath from the `invoices` named-paths group. ``` $invoices.csvpaths.cleanup:to ``` And finally, this version of the reference would run the first csvpath (`print date`) and the second (`cleanup`), but would not run the third csvpath in the group. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://www.csvpath.org/topics/higher-level-topics/organizing-inbound-data/how-data-progresses-through-csvpath-framework/validation-and-upgrading/named-paths-reference-queries.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.