Documentation ¶
Overview ¶
Package search describes and answers Camlistore search queries.
Many of the search methods or functions provide results that are ordered by modification time, or at least depend on modification times. In that context, (un)deletions (of permanodes, or attributes) are not considered modifications and therefore the time at which they occured does not affect the result.
Index ¶
- Constants
- type ClaimConstraint
- type ClaimsItem
- type ClaimsRequest
- type ClaimsResponse
- type Constraint
- type DescribeError
- type DescribeRequest
- func (dr *DescribeRequest) Describe(br blob.Ref, depth int)
- func (dr *DescribeRequest) DescribeSync(br blob.Ref) (*DescribedBlob, error)
- func (dr *DescribeRequest) DescribedBlobStr(blobstr string) *DescribedBlob
- func (dr *DescribeRequest) Result() (desmap map[string]*DescribedBlob, err error)
- func (r *DescribeRequest) URLSuffix() string
- type DescribeResponse
- type DescribedBlob
- func (b *DescribedBlob) ContentRef() (br blob.Ref, ok bool)
- func (b *DescribedBlob) Description() string
- func (b *DescribedBlob) DirMembers() []*DescribedBlob
- func (b *DescribedBlob) DomID() string
- func (b *DescribedBlob) HasSecureLinkTo(other blob.Ref) bool
- func (b *DescribedBlob) Members() []*DescribedBlob
- func (b *DescribedBlob) PeerBlob(br blob.Ref) *DescribedBlob
- func (b *DescribedBlob) PermanodeDir() (path []blob.Ref, fi *camtypes.FileInfo, ok bool)
- func (b *DescribedBlob) PermanodeFile() (path []blob.Ref, fi *camtypes.FileInfo, ok bool)
- func (b *DescribedBlob) Title() string
- type DescribedPermanode
- type DirConstraint
- type EXIFConstraint
- type EdgeItem
- type EdgesRequest
- type EdgesResponse
- type FileConstraint
- type FloatConstraint
- type Handler
- func (sh *Handler) Describe(dr *DescribeRequest) (*DescribeResponse, error)
- func (sh *Handler) EdgesTo(req *EdgesRequest) (*EdgesResponse, error)
- func (sh *Handler) GetClaims(req *ClaimsRequest) (*ClaimsResponse, error)
- func (sh *Handler) GetPermanodesWithAttr(req *WithAttrRequest) (*WithAttrResponse, error)
- func (sh *Handler) GetRecentPermanodes(req *RecentRequest) (*RecentResponse, error)
- func (sh *Handler) GetSignerPaths(req *SignerPathsRequest) (*SignerPathsResponse, error)
- func (h *Handler) Index() index.Interface
- func (sh *Handler) NewDescribeRequest() *DescribeRequest
- func (h *Handler) Owner() blob.Ref
- func (h *Handler) Query(rawq *SearchQuery) (*SearchResult, error)
- func (sh *Handler) ResolvePrefixHop(parent blob.Ref, prefix string) (child blob.Ref, err error)
- func (sh *Handler) ServeHTTP(rw http.ResponseWriter, req *http.Request)
- func (h *Handler) SetCorpus(c *index.Corpus)
- type IGetRecentPermanodes
- type IntConstraint
- type LocationConstraint
- type LogicalConstraint
- type MetaMap
- type PermanodeConstraint
- type PermanodeContinueConstraint
- type RecentItem
- type RecentRequest
- type RecentResponse
- type RelationConstraint
- type SearchQuery
- type SearchResult
- type SearchResultBlob
- type SignerAttrValueResponse
- type SignerPathsItem
- type SignerPathsRequest
- type SignerPathsResponse
- type SortType
- type StringConstraint
- type TimeConstraint
- type WithAttrItem
- type WithAttrRequest
- type WithAttrResponse
Constants ¶
const MaxImageSize = 2000
MaxImageSize is the maximum width or height in pixels that we will serve image thumbnails at. It is used in the search result UI.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ClaimConstraint ¶
type ClaimsItem ¶
type ClaimsItem struct { BlobRef blob.Ref `json:"blobref"` Signer blob.Ref `json:"signer"` Permanode blob.Ref `json:"permanode"` Date types.Time3339 `json:"date"` Type string `json:"type"` Attr string `json:"attr,omitempty"` Value string `json:"value,omitempty"` }
A ClaimsItem is an item returned from $searchRoot/camli/search/claims.
type ClaimsRequest ¶
ClaimsRequest is a request to get a ClaimsResponse.
func (*ClaimsRequest) URLSuffix ¶
func (r *ClaimsRequest) URLSuffix() string
type ClaimsResponse ¶
type ClaimsResponse struct {
Claims []*ClaimsItem `json:"claims"`
}
ClaimsResponse is the JSON response from $searchRoot/camli/search/claims.
type Constraint ¶
type Constraint struct { // If Logical is non-nil, all other fields are ignored. Logical *LogicalConstraint `json:"logical,omitempty"` // Anything, if true, matches all blobs. Anything bool `json:"anything,omitempty"` CamliType string `json:"camliType,omitempty"` // camliType of the JSON blob AnyCamliType bool `json:"anyCamliType,omitempty"` // if true, any camli JSON blob matches BlobRefPrefix string `json:"blobRefPrefix,omitempty"` File *FileConstraint `json:"file,omitempty"` Dir *DirConstraint `json:"dir,omitempty"` Claim *ClaimConstraint `json:"claim,omitempty"` BlobSize *IntConstraint `json:"blobSize,omitempty"` Permanode *PermanodeConstraint `json:"permanode,omitempty"` // contains filtered or unexported fields }
Constraint specifies a blob matching constraint. A blob matches if it matches all non-zero fields' predicates. A zero constraint matches nothing.
type DescribeError ¶
func (DescribeError) Error ¶
func (de DescribeError) Error() string
type DescribeRequest ¶
type DescribeRequest struct { // BlobRefs are the blobs to describe. If length zero, BlobRef // is used. BlobRefs []blob.Ref `json:"blobrefs,omitempty"` // BlobRef is the blob to describe. BlobRef blob.Ref `json:"blobref,omitempty"` // Depth is the optional traversal depth to describe from the // root BlobRef. If zero, a default is used. Depth int `json:"depth,omitempty"` // MaxDirChildren is the requested optional limit to the number // of children that should be fetched when describing a static // directory. If zero, a default is used. MaxDirChildren int `json:"maxDirChildren,omitempty"` // At specifies the time which we wish to see the state of // this blob. If zero (unspecified), all claims will be // considered, otherwise, any claims after this date will not // be considered. At types.Time3339 `json:"at"` // ThumbnailSize sets the max dimension for the thumbnail ULR generated, // or zero for none ThumbnailSize int `json:"thumbnailSize,omitempty"` // contains filtered or unexported fields }
func (*DescribeRequest) Describe ¶
func (dr *DescribeRequest) Describe(br blob.Ref, depth int)
Describe starts a lookup of br, down to the provided depth. It returns immediately.
func (*DescribeRequest) DescribeSync ¶
func (dr *DescribeRequest) DescribeSync(br blob.Ref) (*DescribedBlob, error)
func (*DescribeRequest) DescribedBlobStr ¶
func (dr *DescribeRequest) DescribedBlobStr(blobstr string) *DescribedBlob
Given a blobref string returns a Description or nil. dr may be nil itself.
func (*DescribeRequest) Result ¶
func (dr *DescribeRequest) Result() (desmap map[string]*DescribedBlob, err error)
Result waits for all outstanding lookups to complete and returns the map of blobref (strings) to their described results. The returned error is non-nil if any errors occured, and will be of type DescribeError.
func (*DescribeRequest) URLSuffix ¶
func (r *DescribeRequest) URLSuffix() string
type DescribeResponse ¶
type DescribeResponse struct {
Meta MetaMap `json:"meta"`
}
DescribeResponse is the JSON response from $searchRoot/camli/search/describe.
type DescribedBlob ¶
type DescribedBlob struct { Request *DescribeRequest `json:"-"` BlobRef blob.Ref `json:"blobRef"` CamliType string `json:"camliType,omitempty"` Size int64 `json:"size,"` // if camliType "permanode" Permanode *DescribedPermanode `json:"permanode,omitempty"` // if camliType "file" File *camtypes.FileInfo `json:"file,omitempty"` // if camliType "directory" Dir *camtypes.FileInfo `json:"dir,omitempty"` // if camliType "file", and File.IsImage() Image *camtypes.ImageInfo `json:"image,omitempty"` // if camliType "directory" DirChildren []blob.Ref `json:"dirChildren,omitempty"` Thumbnail string `json:"thumbnailSrc,omitempty"` ThumbnailWidth int `json:"thumbnailWidth,omitempty"` ThumbnailHeight int `json:"thumbnailHeight,omitempty"` // Stub is set if this is not loaded, but referenced. Stub bool `json:"-"` }
func (*DescribedBlob) ContentRef ¶
func (b *DescribedBlob) ContentRef() (br blob.Ref, ok bool)
func (*DescribedBlob) Description ¶
func (b *DescribedBlob) Description() string
func (*DescribedBlob) DirMembers ¶
func (b *DescribedBlob) DirMembers() []*DescribedBlob
func (*DescribedBlob) DomID ¶
func (b *DescribedBlob) DomID() string
func (*DescribedBlob) HasSecureLinkTo ¶
func (b *DescribedBlob) HasSecureLinkTo(other blob.Ref) bool
HasSecureLinkTo returns true if there's a valid link from this blob to the other blob. This is used in access control (hence the somewhat redundant "Secure" in the name) and should be paranoid against e.g. random user/attacker-control attributes making links to other blobs.
TODO: don't linear scan here. rewrite this in terms of ResolvePrefixHop, passing down some policy perhaps? or maybe that's enough.
func (*DescribedBlob) Members ¶
func (b *DescribedBlob) Members() []*DescribedBlob
Members returns all of b's children, as given by b's camliMember and camliPath:* attributes. Only the first entry for a given camliPath attribute is used.
func (*DescribedBlob) PeerBlob ¶
func (b *DescribedBlob) PeerBlob(br blob.Ref) *DescribedBlob
PeerBlob returns a DescribedBlob for the provided blobref.
Unlike DescribedBlobStr, the returned DescribedBlob is never nil.
If the blob was never loaded along with the the receiver (or if the receiver is nil), a stub DescribedBlob is returned with its Stub field set true.
func (*DescribedBlob) PermanodeDir ¶
PermanodeDir returns in path the blobref of the described permanode and the blobref of its Directory camliContent. If b isn't a permanode, or doesn't have a camliContent that is a directory blob, ok is false.
func (*DescribedBlob) PermanodeFile ¶
PermanodeFile returns in path the blobref of the described permanode and the blobref of its File camliContent. If b isn't a permanode, or doesn't have a camliContent that is a file blob, ok is false.
func (*DescribedBlob) Title ¶
func (b *DescribedBlob) Title() string
type DescribedPermanode ¶
type DescribedPermanode struct { Attr url.Values `json:"attr"` // a map[string][]string ModTime time.Time `json:"modtime,omitempty"` }
func (*DescribedPermanode) IsContainer ¶
func (dp *DescribedPermanode) IsContainer() bool
IsContainer returns whether the permanode has either named ("camliPath:"-prefixed) or unnamed ("camliMember") member attributes.
type DirConstraint ¶
type DirConstraint struct { FileName *StringConstraint TopFileSize, TopFileCount, FileSize, FileCount *IntConstraint }
type EXIFConstraint ¶
type EXIFConstraint struct { }
type EdgesRequest ¶
EdgesRequest is a request to get an EdgesResponse.
type EdgesResponse ¶
EdgesResponse is the JSON response from $searchRoot/camli/search/edgesto.
type FileConstraint ¶
type FileConstraint struct { FileSize *IntConstraint `json:"fileSize,omitempty"` FileName *StringConstraint MIMEType *StringConstraint Time *TimeConstraint ModTime *TimeConstraint // For images: IsImage bool `json:"isImage,omitempty"` EXIF *EXIFConstraint `json:"exif,omitempty"` // TODO: implement Width *IntConstraint `json:"width,omitempty"` Height *IntConstraint `json:"height,omitempty"` WHRatio *FloatConstraint `json:"widthHeightRation,omitempty"` Location *LocationConstraint `json:"location,omitempty"` }
type FloatConstraint ¶
type FloatConstraint struct { // Min and Max are both optional and inclusive bounds. // Zero means don't check. Min float64 `json:"min,omitempty"` Max float64 `json:"max,omitempty"` ZeroMin bool `json:"zeroMin,omitempty"` // if true, min is actually zero ZeroMax bool `json:"zeroMax,omitempty"` // if true, max is actually zero }
A FloatConstraint specifies constraints on a float.
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler handles search queries.
func (*Handler) Describe ¶
func (sh *Handler) Describe(dr *DescribeRequest) (*DescribeResponse, error)
func (*Handler) EdgesTo ¶
func (sh *Handler) EdgesTo(req *EdgesRequest) (*EdgesResponse, error)
EdgesTo returns edges that reference req.RefTo. It filters out since-deleted permanode edges.
func (*Handler) GetClaims ¶
func (sh *Handler) GetClaims(req *ClaimsRequest) (*ClaimsResponse, error)
GetClaims returns the claims on req.Permanode signed by sh.owner.
func (*Handler) GetPermanodesWithAttr ¶
func (sh *Handler) GetPermanodesWithAttr(req *WithAttrRequest) (*WithAttrResponse, error)
GetPermanodesWithAttr returns permanodes with attribute req.Attr having the req.Value as a value. See WithAttrRequest for more details about the query.
func (*Handler) GetRecentPermanodes ¶
func (sh *Handler) GetRecentPermanodes(req *RecentRequest) (*RecentResponse, error)
GetRecentPermanodes returns recently-modified permanodes.
func (*Handler) GetSignerPaths ¶
func (sh *Handler) GetSignerPaths(req *SignerPathsRequest) (*SignerPathsResponse, error)
GetSignerPaths returns paths with a target of req.Target.
func (*Handler) NewDescribeRequest ¶
func (sh *Handler) NewDescribeRequest() *DescribeRequest
NewDescribeRequest returns a new DescribeRequest holding the state of blobs and their summarized descriptions. Use DescribeBlob one or more times before calling Result.
func (*Handler) Query ¶
func (h *Handler) Query(rawq *SearchQuery) (*SearchResult, error)
func (*Handler) ResolvePrefixHop ¶
Given a blobref and a few hex characters of the digest of the next hop, return the complete blobref of the prefix, if that's a valid next hop.
type IGetRecentPermanodes ¶
type IGetRecentPermanodes interface { // GetRecentPermanodes returns recently-modified permanodes. // This is a higher-level query returning more metadata than the index.GetRecentPermanodes, // which only scans the blobrefs but doesn't return anything about the permanodes. // TODO: rename this one? GetRecentPermanodes(*RecentRequest) (*RecentResponse, error) }
IGetRecentPermanodes is the interface encapsulating the GetRecentPermanodes query.
type IntConstraint ¶
type IntConstraint struct { // Min and Max are both optional and inclusive bounds. // Zero means don't check. Min int64 `json:"min,omitempty"` Max int64 `json:"max,omitempty"` ZeroMin bool `json:"zeroMin,omitempty"` // if true, min is actually zero ZeroMax bool `json:"zeroMax,omitempty"` // if true, max is actually zero }
An IntConstraint specifies constraints on an integer.
type LocationConstraint ¶
type LogicalConstraint ¶
type LogicalConstraint struct { Op string `json:"op"` // "and", "or", "xor", "not" A *Constraint `json:"a"` B *Constraint `json:"b"` // only valid if Op != "not" }
type MetaMap ¶
type MetaMap map[string]*DescribedBlob
A MetaMap is a map from blobref to a DescribedBlob.
type PermanodeConstraint ¶
type PermanodeConstraint struct { // At specifies the time at which to pretend we're resolving attributes. // Attribute claims after this point in time are ignored. // If zero, the current time is used. At time.Time `json:"at,omitempty"` // ModTime optionally matches on the last modtime of the permanode. ModTime *TimeConstraint `json:"modTime,omitempty"` // Time optionally matches the permanode's time. A Permanode // may not have a known time. If the permanode does not have a // known time, one may be guessed if the top-level search // parameters request so. Time *TimeConstraint `json:"time,omitempty"` // Attr optionally specifies the attribute to match. // e.g. "camliContent", "camliMember", "tag" // This is required if any of the items below are used. Attr string `json:"attr,omitempty"` // SkipHidden skips hidden or other boring files. SkipHidden bool `json:"skipHidden,omitempty"` // NumValue optionally tests the number of values this // permanode has for Attr. NumValue *IntConstraint `json:"numValue,omitempty"` // ValueAll modifies the matching behavior when an attribute // is multi-valued. By default, when ValueAll is false, only // one value of a multi-valued attribute needs to match. If // ValueAll is true, all attributes must match. ValueAll bool `json:"valueAllMatch,omitempty"` // Value specifies an exact string to match. // This is a convenience form for the simple case of exact // equality. The same can be accomplished with ValueMatches. Value string `json:"value,omitempty"` // if non-zero, absolute match // ValueMatches optionally specifies a StringConstraint to // match the value against. ValueMatches *StringConstraint `json:"valueMatches,omitempty"` // ValueMatchesInt optionally specifies an IntConstraint to match // the value against. Non-integer values will not match. ValueMatchesInt *IntConstraint `json:"valueMatchesInt,omitempty"` // ValueMatchesFloat optionally specifies a FloatConstraint to match // the value against. Non-float values will not match. ValueMatchesFloat *FloatConstraint `json:"valueMatchesFloat,omitempty"` // ValueInSet optionally specifies a sub-query which the value // (which must be a blobref) must be a part of. ValueInSet *Constraint `json:"valueInSet,omitempty"` // Relation optionally specifies a constraint based on relations // to other permanodes (e.g. camliMember or camliPath sets). // You can use it to test the properties of a parent, ancestor, // child, or progeny. Relation *RelationConstraint `json:"relation,omitempty"` // Continue is for internal use. Continue *PermanodeContinueConstraint `json:"-"` }
PermanodeConstraint matches permanodes.
type PermanodeContinueConstraint ¶
type PermanodeContinueConstraint struct { // LastMod if non-zero is the modtime of the last item // that was seen. One of this or LastCreated will be set. LastMod time.Time // Last is the last blobref that was shown at the time // given in ModLessEqual or CreateLessEqual. // This is used as a tie-breaker. // If the time is equal, permanodes <= this are not matched. // If the time is past this in the scroll position, then this // field is ignored. Last blob.Ref }
type RecentItem ¶
type RecentItem struct { BlobRef blob.Ref `json:"blobref"` ModTime types.Time3339 `json:"modtime"` Owner blob.Ref `json:"owner"` }
A RecentItem is an item returned from $searchRoot/camli/search/recent in the "recent" list.
type RecentRequest ¶
type RecentRequest struct { N int // if zero, default number of results Before time.Time // if zero, now ThumbnailSize int // if zero, no thumbnails }
RecentRequest is a request to get a RecentResponse.
func (*RecentRequest) URLSuffix ¶
func (r *RecentRequest) URLSuffix() string
type RecentResponse ¶
type RecentResponse struct { Recent []*RecentItem `json:"recent"` Meta MetaMap `json:"meta"` Error string `json:"error,omitempty"` ErrorType string `json:"errorType,omitempty"` }
RecentResponse is the JSON response from $searchRoot/camli/search/recent.
func (*RecentResponse) Err ¶
func (r *RecentResponse) Err() error
type RelationConstraint ¶
type RelationConstraint struct { // Relation must be one of: // // * "child" // * "progeny" (any level down) // * "parent" (immediate parent only) // * "ancestor" (any level up) Relation string // EdgeType optionally specifies an edge type. // By default it matches "camliMember" and "camliPath:*". EdgeType string // After finding all the nodes matching the Relation and // EdgeType, either one or all (depending on whether Any or // All is set) must then match for the RelationConstraint // itself to match. // // It is an error to set both. Any, All *Constraint }
type SearchQuery ¶
type SearchQuery struct { // Expression is a textual search query in minimal form, // e.g. "hawaii before:2008" or "tag:foo" or "foo" or "location:portland" // See expr.go and expr_test.go for all the operators. Expression string `json:"expression,omitempty"` Constraint *Constraint `json:"constraint,omitempty"` Limit int `json:"limit,omitempty"` // optional. default is automatic. negative means no limit. Sort SortType `json:"sort,omitempty"` // optional. default is automatic or unsorted. // Continue specifies the opaque token (as returned by a // SearchResult) for where to continue fetching results when // the Limit on a previous query was interrupted. // Continue is only valid for the same query (Expression or Constraint), // Limit, and Sort values. // If empty, the top-most query results are returned, as given // by Limit and Sort. Continue string `json:"continue,omitempty"` // If Describe is specified, the matched blobs are also described, // as if the Describe.BlobRefs field was populated. Describe *DescribeRequest `json:"describe,omitempty"` }
func (*SearchQuery) URLSuffix ¶
func (q *SearchQuery) URLSuffix() string
type SearchResult ¶
type SearchResult struct { Blobs []*SearchResultBlob `json:"blobs"` Describe *DescribeResponse `json:"description"` // Continue optionally specifies the continuation token to to // continue fetching results in this result set, if interrupted // by a Limit. Continue string `json:"continue,omitempty"` }
SearchResult is the result of the Search method for a given SearchQuery.
type SearchResultBlob ¶
func (*SearchResultBlob) String ¶
func (r *SearchResultBlob) String() string
type SignerAttrValueResponse ¶
type SignerAttrValueResponse struct { Permanode blob.Ref `json:"permanode"` Meta MetaMap `json:"meta"` }
SignerAttrValueResponse is the JSON response to $search/camli/search/signerattrvalue
type SignerPathsItem ¶
type SignerPathsItem struct { ClaimRef blob.Ref `json:"claimRef"` BaseRef blob.Ref `json:"baseRef"` Suffix string `json:"suffix"` }
A SignerPathsItem is an item returned from $searchRoot/camli/search/signerpaths.
type SignerPathsRequest ¶
SignerPathsRequest is a request to get a SignerPathsResponse.
type SignerPathsResponse ¶
type SignerPathsResponse struct { Paths []*SignerPathsItem `json:"paths"` Meta MetaMap `json:"meta"` }
SignerPathsResponse is the JSON response from $searchRoot/camli/search/signerpaths.
type StringConstraint ¶
type StringConstraint struct { Empty bool `json:"empty,omitempty"` // matches empty string Equals string `json:"equals,omitempty"` Contains string `json:"contains,omitempty"` HasPrefix string `json:"hasPrefix,omitempty"` HasSuffix string `json:"hasSuffix,omitempty"` ByteLength *IntConstraint `json:"byteLength,omitempty"` // length in bytes (not chars) CaseInsensitive bool `json:"caseInsensitive,omitempty"` }
A StringConstraint specifies constraints on a string. All non-zero must match.
type TimeConstraint ¶
type WithAttrItem ¶
A WithAttrItem is an item returned from $searchRoot/camli/search/permanodeattr.
type WithAttrRequest ¶
type WithAttrRequest struct { N int // max number of results Signer blob.Ref // if nil, will use the server's default owner (if configured) // Requested attribute. If blank, all attributes are searched (for Value) // as fulltext. Attr string // Value of the requested attribute. If blank, permanodes which have // request.Attr as an attribute are searched. Value string Fuzzy bool // fulltext search (if supported). ThumbnailSize int // if zero, no thumbnails }
WithAttrRequest is a request to get a WithAttrResponse.
func (*WithAttrRequest) URLSuffix ¶
func (r *WithAttrRequest) URLSuffix() string
type WithAttrResponse ¶
type WithAttrResponse struct { WithAttr []*WithAttrItem `json:"withAttr"` Meta MetaMap `json:"meta"` Error string `json:"error,omitempty"` ErrorType string `json:"errorType,omitempty"` }
WithAttrResponse is the JSON response from $searchRoot/camli/search/permanodeattr.
func (*WithAttrResponse) Err ¶
func (r *WithAttrResponse) Err() error