Operadores do Filtered Stream

Referência dos operadores do Filtered Stream da X API v2: operadores de palavra-chave, has:, is: e o operador embedding: exclusivo do Enterprise.

Esta página fornece uma lista completa dos operadores disponíveis ao criar regras para o Filtered Stream.

Visão geral

Os operadores são usados para corresponder a atributos específicos de posts. Existem dois tipos:

• Operadores independentes — Podem ser usados sozinhos ou com quaisquer outros operadores
• Operadores que exigem conjunção — Devem ser usados com pelo menos um operador independente

A maioria dos operadores está disponível tanto no Pay-per-use quanto no Enterprise. Alguns operadores avançados (como o de similaridade semântica) exigem Enterprise com acesso a um tier adicional.

---

Operadores de palavra-chave e frase

Operador	Tipo	Resumo	Exemplo
keyword	Independente	Corresponde a uma palavra-chave no corpo do post (correspondência tokenizada)	pepsi OR cola OR "coca cola"
emoji	Independente	Corresponde a um emoji no corpo do post	(😃 OR 😡) 😬
"exact phrase"	Independente	Corresponde à frase exata no corpo do post	("X API" OR #v2) -"filtered stream"
"keyword1 keyword2"~N	Independente	Correspondência por proximidade — palavras-chave a até N tokens de distância (N máximo = 6)	"social media"~5

---

Operadores de entidade

Operador	Tipo	Resumo	Exemplo
#	Independente	Corresponde a posts que contêm uma hashtag (correspondência exata)	#thankunext #fanart
@	Independente	Corresponde a posts que mencionam um nome de usuário	(@XDevelopers OR @api) -@x
$	Independente	Corresponde a posts que contêm uma cashtag	$twtr OR @XDevelopers -$fb

---

Operadores de usuário

Operador	Tipo	Resumo	Exemplo
from:	Independente	Corresponde a posts de um usuário específico	from:XDevelopers OR from:api
to:	Independente	Corresponde a posts em resposta a um usuário específico	to:XDevelopers OR to:api
retweets_of:	Independente	Corresponde a reposts de um usuário específico	retweets_of:XDevelopers
from_affiliate_of:	Independente	Corresponde a posts de afiliados de um usuário específico	from_affiliate_of:XDevelopers
to_affiliate_of:	Independente	Corresponde a posts em resposta a afiliados de um usuário específico	to_affiliate_of:XDevelopers

---

Operadores de URL

Operador	Tipo	Resumo	Exemplo
url:	Independente	Correspondência tokenizada em URLs (corresponde aos campos url ou expanded_url)	url:"https://developer.x.com"
url_title:	—	Correspondência por palavra-chave nos metadados do título HTML da URL expandida	url_title:snow
url_description:	—	Correspondência por palavra-chave nos metadados de descrição da página expandida	url_description:weather
url_contains:	—	Correspondência literal no conteúdo da URL	url_contains:photos

---

Operadores de contexto e entidade

Operador	Tipo	Resumo	Exemplo
context:	Independente	Corresponde a posts com um par específico de domínio/entidade	context:10.799022225751871488 ou context:47.*
entity:	Independente	Corresponde a posts com um valor de string de entidade específico	entity:"Michael Jordan"
conversation_id:	Independente	Corresponde a posts em uma thread de conversa	conversation_id:1334987486343299072

---

Operadores de perfil de usuário

Operador	Tipo	Resumo	Exemplo
bio:	Independente	Corresponde a uma palavra-chave na bio do autor do post	bio:developer OR bio:"data engineer"
bio_name:	Independente	Corresponde a uma palavra-chave no nome do autor do post	bio_name:phd OR bio_name:md
bio_location:	Independente	Corresponde a uma palavra-chave na localização do autor do post	bio_location:"big apple" OR bio_location:nyc

---

Operadores de localização

Operador	Tipo	Resumo	Exemplo
place:	Independente	Corresponde a posts marcados com uma localização	place:"new york city" OR place:seattle
place_country:	Independente	Corresponde a posts com um código de país	place_country:US OR place_country:MX
point_radius:	Independente	Corresponde a posts dentro do raio de um ponto	point_radius:[2.355128 48.861118 16km]
bounding_box:	Independente	Corresponde a posts dentro de uma bounding box	bounding_box:[-105.301758 39.964069 -105.178505 40.09455]

---

Operadores de tipo de post

Operador	Tipo	Resumo	Exemplo
is:retweet	Exige conjunção	Corresponde a reposts	data @XDevelopers -is:retweet
is:reply	Exige conjunção	Corresponde a respostas	from:XDevelopers is:reply
is:quote	Exige conjunção	Corresponde a quote tweets	"sentiment analysis" is:quote
is:verified	Exige conjunção	Corresponde a posts de autores verificados	#nowplaying is:verified
-is:nullcast	Exige conjunção	Exclui posts promocionais (deve ser negado)	"mobile games" -is:nullcast

---

Operadores de tipo de conteúdo

Operador	Tipo	Resumo	Exemplo
has:hashtags	Exige conjunção	Corresponde a posts com hashtags	from:XDevelopers -has:hashtags
has:cashtags	Exige conjunção	Corresponde a posts com cashtags	#stonks has:cashtags
has:links	Exige conjunção	Corresponde a posts com links	from:XDevelopers has:links
has:mentions	Exige conjunção	Corresponde a posts com menções	#nowplaying has:mentions
has:media	Exige conjunção	Corresponde a posts com mídia (foto, GIF, vídeo)	(kittens OR puppies) has:media
has:images	Exige conjunção	Corresponde a posts com imagens	#meme has:images
has:video_link	Exige conjunção	Corresponde a posts com vídeos nativos do X	#icebucketchallenge has:video_link
has:geo	Exige conjunção	Corresponde a posts com dados de geolocalização	recommend #paris has:geo

---

Operadores de amostragem e idioma

Operador	Tipo	Resumo	Exemplo
sample:	Exige conjunção	Retorna uma amostra aleatória em porcentagem (1-100)	#nowplaying @spotify sample:15
lang:	Exige conjunção	Corresponde a posts classificados em um idioma específico	recommend #paris lang:en

---

Operadores de métricas de usuário

Operador	Tipo	Resumo	Exemplo
min_followers:	—	Corresponde a posts de usuários com pelo menos o número de seguidores especificado	min_followers:1000
followers_count:	—	Corresponde a posts de usuários com contagem de seguidores no intervalo	followers_count:1000..10000
tweets_count:	—	Corresponde a posts de usuários com contagem de posts no intervalo	tweets_count:1000..10000
following_count:	—	Corresponde a posts de usuários com contagem de contas seguidas no intervalo	following_count:1000..10000
listed_count:	—	Corresponde a posts de usuários presentes no número de listas especificado	listed_count:10..100

---

Operadores de referência a post

Operador	Tipo	Resumo	Exemplo
in_reply_to_tweet_id:	—	Corresponde a respostas a um post específico	in_reply_to_tweet_id:1539382664746020864
retweets_of_tweet_id:	—	Corresponde a reposts de um post específico	retweets_of_tweet_id:1539382664746020864
source:	—	Corresponde a posts de um aplicativo de origem específico	source:"X for iPhone"

---

Operadores lógicos

Operador	Resumo	Exemplo
OR	OR lógico entre expressões	cat OR dog
Espaço (AND)	AND lógico entre expressões	cat dog (ambos obrigatórios)
()	Agrupamento para expressões complexas	(cat OR dog) -is:retweet
-	Negação/exclusão	cat -grumpy

---

Operadores de embedding

Apenas Enterprise — Tier de Embedding obrigatório

Os operadores embedding: e embedding_threshold: só estão disponíveis em contas Enterprise provisionadas com acesso ao tier de Embedding para o Filtered Stream. Em tiers não suportados, a criação de regras será rejeitada com um erro “unavailable operator”. Entre em contato com seu representante de conta para habilitar.

Esses operadores usam um modelo neural de embedding para corresponder a posts por similaridade semântica em relação a uma consulta, em vez de exigir correspondências exatas de palavras-chave.

Operador	Tipo	Resumo	Exemplo
embedding:"query"	Independente	Corresponde a posts semanticamente semelhantes à consulta. Consultas com várias palavras devem estar entre aspas.	embedding:"climate change policy"
embedding_threshold:X.XX	Exige conjunção	Similaridade de cosseno mínima para uma correspondência (0,0–1,0). O padrão é 0.3. Use valores entre 0,3–0,6.	embedding:"cryptocurrency regulation" embedding_threshold:0.45

Requisitos e observações importantes

• embedding_threshold: não pode ser o único operador em uma regra. Combine-o com embedding: (ou outro operador independente).
• Não negue embedding: (por exemplo, -embedding:"..." não é suportado).
• Consultas em linguagem natural mais longas e descritivas produzem resultados melhores do que palavras-chave curtas.
• O processamento de consultas de embedding é assíncrono — regras recém-criadas podem levar alguns segundos antes de começar a corresponder.
• Quando um post corresponde por meio de uma regra de embedding, as entradas de matching_rules no payload entregue conterão embedding_similarity e embedding_threshold (consulte Correspondência de posts a regras).

Exemplos de regras:

• embedding:"electric vehicle announcements" lang:en -is:retweet has:links
• embedding:"natural disaster relief" embedding_threshold:0.45 has:media
• embedding:"renewable energy" embedding_threshold:0.4 OR embedding:"solar power investment"

---

Idiomas suportados

O operador lang: suporta os seguintes códigos de idioma BCP 47:

Idioma	Código	Idioma	Código	Idioma	Código
Amárico	am	Grego	el	Português	pt
Árabe	ar	Guzerate	gu	Romeno	ro
Armênio	hy	Hebraico	iw	Russo	ru
Basco	eu	Hindi	hi	Sérvio	sr
Bengali	bn	Húngaro	hu	Chinês simplificado	zh-CN
Búlgaro	bg	Indonésio	in	Eslovaco	sk
Catalão	ca	Italiano	it	Esloveno	sl
Croata	hr	Japonês	ja	Espanhol	es
Tcheco	cs	Canarês	kn	Sueco	sv
Dinamarquês	da	Coreano	ko	Tâmil	ta
Holandês	nl	Letão	lv	Télugo	te
Inglês	en	Lituano	lt	Tailandês	th
Estoniano	et	Malaiala	ml	Chinês tradicional	zh-TW
Finlandês	fi	Marata	mr	Turco	tr
Francês	fr	Norueguês	no	Ucraniano	uk
Alemão	de	Persa	fa	Urdu	ur
Georgiano	ka	Polonês	pl	Vietnamita	vi

---

Próximas etapas

Criar uma regra

Aprenda a sintaxe das regras e as práticas recomendadas

Introdução ao Filtered Stream

Comece a usar o Filtered Stream

Lidando com desconexões

Lide com desconexões em streaming