PostGIS 1.4 documentation update

[mcayland]

Most of the examples in the documentation still refer to the non ST_ variants of the PostGIS functions.

Given that these functions are deprecated, we really should not be trying to encourage their use ;)

[mcayland]

Hmmm I also just noticed that the operators section is empty in the 1.4-SVN documentation too :(

ATB,

Mark.

[robe]

Its still in the old section. It is on my todo and Kevin's todo to figure out how to bring it into the new section.

I think Kevin was talking about new tags to describe the operators -- Here is a snippet from his email. Kevin you want to do the template and I'll move over the operators. Let me know if you need help with the xsl. I think I can write the xsl stylesheet, but not sure how to integrate it with the doc book build.

Maybe something like this:  http://www.docbook.org/tdg/en/html/ch05.html#ex.addsect6 and extend the refentry to include an operatorsynopsis or something.

---Other relevant excerpts from our correspondence - snippet from Kevin's email to me --

I've been

fighting with getting the Operators moved over, but, there doesn't seem to be proper tags for an operator type. It looks funny using the standard functionsynopsis tag. I'm thinking that a custom xsl parser could be written and and added to the docbook xsl parser. I've done very little to no work with stylesheets in the past. Any idea how we can make such a thing happen?

[robe]

Are you sure most. Most seemed to have the new ST. Anyrate I fixed the few I found that were an issue. Can you point out others you see that are missing the ST_?

[mcayland]

Okay... maybe most was a little exaggeration! I guess it was just the sections I was looking at:

4.1.1 4.1.2 4.3.1 4.4.1 4.6.1

Most of them are GeomFromText?() missing the ST_ prefix, which I assume since we are moving towards SQL-MM should be the way forward?

ATB,

Mark.

[robe]

Alright that's what I thought. I macro replaced all those -- so check it out and see if I missed a spot.

[mcayland]

Thanks Regina, that look good to me. So it's now just the operators outstanding, which hopefully you and Kevin will be able to solve :)

ATB,

Mark.

[mcayland]

Okay, so I see that the operators have now gone into the SVN documentation. The interesting part is that most of the operators are labelled as 'This operand will NOT make use of any indexes that may be available on the geometries' but this is totally untrue; please see lwgeom_gist.c:lwgeom_rtree_internal_consistent and you'll see that all operators support index usage!

ATB,

Mark.

[kneufeld]

As I ported all the operators over, I tested each one with against a multi-gigabyte linear table. Only a few ever invoked the GIST index. It occurred to me just now that I might have done that against a slightly older PostGIS version. Were they always supposed to invoke the index, or was this a recent change? I'll have to retest against SVN head...

-- Kevin

[mcayland]

Kevin,

I suspect it's because anything other than && uses the in-built PostgreSQL selectivity estimates (which are fairly useless!). You should be able to force use with 'set enable_seqscan = 'f though.

ATB,

Mark.

[kneufeld]

Ah.. of course it's all about selectivity. If overleft represents a significant portion of a table, it obviously won't use the index ... K. I'll have to change the Note. -- Kevin

[robe]

<i>(No comment was entered for this change.)</i>

[kneufeld]

I updated the note on operators to reflect the fact the fact that they do indeed use indexes.

However, the caution on the = operator is left as is. For the life of me, I can't engage the index using this operator no matter what kind of selectivity I try for a large spatial table.

Mark, are you sure that every operator uses indexes? I don't think this one does.

CREATE TABLE foo AS

SELECT st_makepoint(random(), random()) AS the_geom FROM generate_series(1, 100000);

CREATE INDEX foo_geom_idx ON foo using gist (the_geom); ANALYZE foo; EXPLAIN SELECT * FROM foo WHERE the_geom &amp;&amp; 'POINT(0.5 0.5)';

QUERY PLAN

---

Index Scan using foo_geom_idx on foo (cost=0.00..8.29 rows=1 width=84)

Index Cond: (the_geom &amp;&amp; '0101000000000000000000E03F000000000000E03F'::geometry)

(2 rows)

EXPLAIN SELECT * FROM foo WHERE the_geom = 'POINT(0.5 0.5)';

QUERY PLAN

---

Seq Scan on foo (cost=0.00..1839.00 rows=100 width=84)

Filter: (the_geom = '0101000000000000000000E03F000000000000E03F'::geometry)

(2 rows)

-- Kevin

[mcayland]

Hi Kevin.

Remember that only &amp;&amp; has a selectivity function that will be anywhere meaningful. Just because an operator is indexable, doesn't mean that the planner *has* to use it. What happens if you do a 'SET enable_seqscan = 'f before trying your query?

ATB,

Mark.

[kneufeld]

Granted. But if the planner never uses the index, then the caution note still stands, no? If the = operator is indexable, what am I doing wrong here that it's not engaging?

postgis=# set enable_seqscan = false; SET postgis=# EXPLAIN SELECT * FROM foo WHERE the_geom = 'POINT(0.5 0.5)';

QUERY PLAN

---

Seq Scan on foo (cost=100000000.00..100001839.00 rows=100 width=84)

Filter: (the_geom = '0101000000000000000000E03F000000000000E03F'::geometry)

(2 rows)

[mcayland]

Off the top of my head, I don't know as I would have expected that to work. I suspect I shall probably be looking at the selectivity code for the new bug over the next couple of days, so maybe that will help.

ATB,

Mark.

[robe]

I think we are done with this documentation wise.