How do v.distance 'upload' parameters actually work?

Question

I'm trying to use v.distance (using QGIS 3.4) to calculate the distance in meters between a layer of water shutoff points and the boundary of the nearest building footprint polygon. Even better would be the distance to building footprint with a matching "ASSOC_SC" value (associated service connection).

I have tried many, many different combinations to try and satisfy the 'upload' section of the function parameters and I cannot for the life of me understand how exactly it works.

Do I need to create an empty column of the right data type in my 'from' layer for the chosen measurement result to go and then choose that in the "Column name of the nearest..." section? (e.g. to match cat for identifying nearest, distance for listing the actual measurement, etc.) When I do that, it does not work.

If I'm trying to measure based on a matching ID attribute, why does it ask me to select "to_attr)" in the "'upload: Values..." section and then not list any of the columns in the "Column name of the nearest..." section?

What does that "Column name of the nearest..." language actually mean?

It allows me to choose an ID column from my 'to' layer in the dropdown below but nowhere allows me to select from my 'from' layer what to match...

Has anyone made use of this function from the QGIS processing toolbox like this?

All layers are in the same CRS, etc.

Answer 1

Here's the classic use of v.distance: ("From" layer is the points, and attributes will be added to this layer. "To" layer is the building polygons)

# First add required new columns to the "from" layer
v.db.addcolumn map=water_shutoff column="dist DOUBLE PRECISION, assoc_sc INTEGER"
# Run v.distance once to get the distance
v.distance from=water_shutoff to=buildings upload=dist column=dist
# Run v.distance a second time to get the assoc_sc value from buildings
v.distance from=water_shutoff to=buildings upload=attr column=assoc_sc to_column=ASSOC_SC

Reading thru your question, I might have misunderstood: If you need the distance from a specific water_shutoff to a specific building - not necessarily the closest - (you mentioned "matching ID") then v.distance is not the right tool. You might have to construct an SQL query to get the distance between a certain point feature and a certain polygon feature.